JS with Types

A JSDoc style guide for type-checked JavaScript

2026-10-21T00:00:00Z

House rules for JSDoc that TypeScript checks: one comment style, where @typedefs live, naming, @import, @satisfies over casts, and Prettier settings.

Checking JavaScript in CI

2026-10-21T00:00:00Z

Run tsc on every pull request: a GitHub Actions workflow, caching, monorepos, a pre-commit hook, and failing only on new errors with a baseline file.

Checking JavaScript in Node.js, Deno and Bun

2026-10-21T00:00:00Z

What each runtime checks before and while it runs your JavaScript, which config each reads, and the commands, with one sample file checked by tsc.

Choosing a strictness level for checked JavaScript

2026-10-21T00:00:00Z

Relaxed, recommended or strict: what each level of jsconfig.json strictness catches, what it costs in an existing codebase, and an order to turn options on.

How do I add a property to a type from another package?

2026-10-21T00:00:00Z

Module augmentation for checked JavaScript: add req.user to Express's Request in a .d.ts with declare global, so middleware and handlers agree on it.

How do I add types for an npm package that has none?

2026-10-21T00:00:00Z

Write a local .d.ts with declare module for a dependency that ships no types, so checked JavaScript gets real types instead of TS7016 or any.

How do I check a config object without losing its literal types?

2026-10-21T00:00:00Z

Use JSDoc @satisfies (TypeScript 5.0+) on a config object: tsc checks it against a type while keeping its own keys and literal values for later use.

How do I create .d.ts files from my JavaScript with tsc?

2026-10-21T00:00:00Z

Let tsc write .d.ts files from JSDoc-typed JavaScript with a second config, jsconfig.types.json: declaration, emitDeclarationOnly, declarationDir.

How do I declare a global variable or add a property to window?

2026-10-21T00:00:00Z

Declare globals for checked JavaScript in a .d.ts file: window.dataLayer through the Window interface, and constants a bundler injects, with declare global.

How do I import a JSON file in checked JavaScript?

2026-10-21T00:00:00Z

Import a JSON file in a Node.js ES module with with { type: "json" }; tsc types it from the file. Fix TS1543, TS1544 and resolveJsonModule settings.

How do I import and re-export types between JavaScript files?

2026-10-21T00:00:00Z

Share @typedef types between JavaScript files with @import (TypeScript 5.5+) or import() types, re-export them from one module, and fix TS18042.

How do I make a JavaScript class implement an interface?

2026-10-21T00:00:00Z

Use @implements in checked JavaScript to make a class promise the shape of a @typedef, so tsc reports missing methods and wrong signatures in the class.

How do I mark a parameter as optional in JSDoc?

2026-10-21T00:00:00Z

Optional and default parameters in JSDoc: square brackets in @param, JavaScript defaults, and what tsc reports when a caller or the function gets it wrong.

How do I narrow a union of object types in JavaScript?

2026-10-21T00:00:00Z

Write a discriminated union in JSDoc with a shared kind property, narrow it with switch or if, and make tsc report any case you forget to handle.

How do I publish a JavaScript package with types?

2026-10-21T00:00:00Z

Ship .d.ts files with a JavaScript package: point the types condition of exports at them, list them in files, and check the result from a consumer project.

How do I return a tuple from a JavaScript function?

2026-10-21T00:00:00Z

Return a tuple from a checked JavaScript function with @returns {[inStock: boolean, quantity: number]}, or a const cast, so destructuring keeps each type.

How do I type "this" inside a JavaScript function?

2026-10-21T00:00:00Z

Tell tsc what this is in a plain JavaScript function with the JSDoc @this tag, and fix TS2683 (this implicitly has type any) and TS2684 at the call.

How do I type a callback parameter in JSDoc?

2026-10-21T00:00:00Z

Type callback parameters in JSDoc with @callback or an inline arrow type, so tsc checks the callback's arguments and its return value in plain JavaScript.

How do I type a CLI's options with util.parseArgs?

2026-10-21T00:00:00Z

Use util.parseArgs in checked JavaScript: options typed from the config object, values that may be missing, and why a config built apart loses its types.

How do I type a Cloudflare Workers fetch handler and its bindings in JavaScript?

2026-10-21T00:00:00Z

Check a fetch handler in plain JavaScript with @satisfies {ExportedHandler} and a @typedef for the bindings in wrangler.jsonc, so tsc checks env.

How do I type a custom element (Web Component) in JavaScript?

2026-10-21T00:00:00Z

Type a custom element class in checked JavaScript and register its tag in HTMLElementTagNameMap, so querySelector and createElement return your class.

How do I type a dynamic import() in JavaScript?

2026-10-21T00:00:00Z

A dynamic import() in checked JavaScript is typed from the module it loads. Type a lazily loaded module variable with typeof import(), and fix TS2835.

How do I type a function that also has properties?

2026-10-21T00:00:00Z

Type a JavaScript function that carries properties (formatPrice.symbol): assignments after the function, a @type on the first one, or a call signature type.

How do I type a Map or a Set in JSDoc?

2026-10-21T00:00:00Z

Type a Map or Set in checked JavaScript with @type {Map}, why an empty new Map() is any, and why get() can return undefined.

How do I type a mixin in JavaScript?

2026-10-21T00:00:00Z

Type a class mixin in checked JavaScript with @template over a constructor type, so the mixed class keeps the base class's members and adds its own.

How do I type a Node.js EventEmitter's events in JavaScript?

2026-10-21T00:00:00Z

Give an EventEmitter an event map with @extends in checked JavaScript, so emit() and on() check event names and their arguments.

How do I type a reducer and its actions in JavaScript?

2026-10-21T00:00:00Z

Type a reducer in checked JavaScript: the state as a @typedef, the actions as a union keyed by type, so each case knows its payload and bad dispatches fail.

How do I type a subclass in JavaScript with @extends and @override?

2026-10-21T00:00:00Z

Subclasses in checked JavaScript: extends does the typing, @extends supplies a generic base's type argument, and @override marks overrides tsc can verify.

How do I type an async generator in JSDoc?

2026-10-21T00:00:00Z

Type async generators and async iterators in checked JavaScript with @returns {AsyncGenerator}, and loop over them with for await.

How do I type an Express handler in JavaScript?

2026-10-21T00:00:00Z

Type Express route handlers in plain JavaScript with JSDoc and @types/express: route parameters, request bodies and error handlers, checked by tsc.

How do I type an object whose keys are a fixed set of strings?

2026-10-21T00:00:00Z

Type a lookup object keyed by a union of strings with Record in JSDoc, so tsc reports a missing key, an unknown key and a wrong value.

How do I type an options object with default values in JSDoc?

2026-10-21T00:00:00Z

Type an options parameter in JSDoc with a @typedef of optional properties, defaults by destructuring or spread, and the typos and values tsc catches.

How do I type Buffers and Uint8Arrays in JSDoc?

2026-10-21T00:00:00Z

Accept bytes as Uint8Array in checked JavaScript, so functions take Node.js Buffers and browser data alike, and avoid Buffer-only methods tsc will flag.

How do I type child_process results in Node.js JavaScript?

2026-10-21T00:00:00Z

Checked JavaScript with node:child_process: promisify(execFile) gives typed stdout and stderr, spawn's streams depend on stdio, and exit codes can be null.

How do I type class fields and the constructor in JavaScript?

2026-10-21T00:00:00Z

Type class fields in checked JavaScript: @type on field declarations, constructor parameters with @param, and the TS7008, TS2564 and null traps.

How do I type document.querySelector results in JavaScript?

2026-10-21T00:00:00Z

querySelector returns Element | null. Narrow it in checked JavaScript with instanceof, tag-name selectors or a JSDoc cast, and fix TS18047 and TS2339.

How do I type event handlers and addEventListener in JavaScript?

2026-10-21T00:00:00Z

addEventListener types the event from its name. Use the element from the closure, not event.target, and fix TS18047, TS2339 and TS2345 in checked JavaScript.

How do I type Express middleware and error handlers in JavaScript?

2026-10-21T00:00:00Z

Type Express middleware in checked JavaScript: RequestHandler for middleware and factories, res.locals via its fifth type parameter, and ErrorRequestHandler.

How do I type getters and setters in a JavaScript class?

2026-10-21T00:00:00Z

Type get and set accessors in checked JavaScript: @returns on the getter, @param on the setter, a setter that accepts more types, and read-only getters.

How do I type module.exports and require() in CommonJS JavaScript?

2026-10-21T00:00:00Z

Checked CommonJS: tsc types module.exports and require() from your JSDoc, shares typedefs with import() types, and catches names a module does not export.

How do I type Node.js fs callbacks and fs/promises in JavaScript?

2026-10-21T00:00:00Z

Checked JavaScript with node:fs: error-first callbacks typed by @types/node, fs/promises with await, the encoding that turns a Buffer into a string.

How do I type Node.js streams in checked JavaScript?

2026-10-21T00:00:00Z

Type stream code in checked JavaScript: readline's line iterator, pipeline() with an async generator, and chunks, which arrive as any until you type them.

How do I type process.env variables in JavaScript?

2026-10-21T00:00:00Z

process.env values are string | undefined. Read each variable once in a checked config module, or declare them on NodeJS.ProcessEnv in a .d.ts file.

How do I type React component props in a .jsx file?

2026-10-21T00:00:00Z

Type React props in plain .jsx files with a @typedef and @param, so tsc checks every use of the component, its state and its handlers, with @types/react.

How do I type rest parameters (...args) in JSDoc?

2026-10-21T00:00:00Z

Type a rest parameter in JSDoc with @param {...number} or an array type, spread arrays into calls, and fix TS2345 and TS2556 in checked JavaScript.

How do I type static properties and methods in a JavaScript class?

2026-10-21T00:00:00Z

Static fields, private static fields and static factory methods in checked JavaScript: how tsc types them, and the TS2576 you get from an instance.

How do I type Svelte component props in JavaScript?

2026-10-21T00:00:00Z

Type Svelte 5 props in a JavaScript component with a @type on the $props() destructuring; svelte-check reads it, and tsc checks the shared .js modules.

How do I type the JSON from a fetch response in JavaScript?

2026-10-21T00:00:00Z

response.json() returns Promise. Check response.ok, then annotate the parsed body with @type, or parse into unknown and narrow it, in checked JavaScript.

How do I type the result of JSON.parse in JavaScript?

2026-10-21T00:00:00Z

JSON.parse returns any. Type its result in checked JavaScript: parse into unknown and check it, or cast with @type when you trust the source.

How do I type the results of Promise.all in JavaScript?

2026-10-21T00:00:00Z

Keep each result's type from Promise.all in checked JavaScript: pass the promises as an array literal, and narrow Promise.allSettled results by status.

How do I type values from localStorage in JavaScript?

2026-10-21T00:00:00Z

localStorage holds strings, and getItem can return null. Wrap it in checked JavaScript with a small @template helper that parses JSON and falls back.

How do I type WebSocket and EventSource messages in JavaScript?

2026-10-21T00:00:00Z

Socket and server-sent event messages arrive as any. Parse them into unknown, narrow them with a type guard over a union, and send only strings or bytes.

How do I type what an async function returns in JSDoc?

2026-10-21T00:00:00Z

Type an async function's result in JSDoc with @returns {Promise}, and fix TS1064 and the TS2339 you get from a missing await in checked JavaScript.

How do I type-check Vitest or Jest test files in JavaScript?

2026-10-21T00:00:00Z

Check JavaScript test files with tsc: import describe and expect from vitest, or list vitest/globals in types; fix TS2593 'Cannot find name describe'.

How do I write a generic function in JavaScript with @template?

2026-10-21T00:00:00Z

Write generic helper functions in plain JavaScript with JSDoc @template: type parameters, constraints with {...}, keyof keys, and the errors tsc reports.

How do I write a type guard function in JSDoc?

2026-10-21T00:00:00Z

Write a type guard in checked JavaScript with @returns {value is Product}, so a check in one function narrows the value in every caller and in filter.

How do I write an assertion function in JSDoc?

2026-10-21T00:00:00Z

Write assert() helpers in checked JavaScript with @returns {asserts value is string}, and fix TS2775 when an assertion is called through an untyped variable.

How do I write an enum in JavaScript with JSDoc?

2026-10-21T00:00:00Z

JavaScript has no enum keyword. Use a frozen object for the values and a @typedef of their union, so tsc checks every status your code passes around.

How do I write function overloads in JavaScript?

2026-10-21T00:00:00Z

Declare function overloads in a .js file with JSDoc @overload (TypeScript 5.0 and later), so each call gets the return type that matches its arguments.

How TypeScript reads a JavaScript file

2026-10-21T00:00:00Z

How tsc reads a .js file: types from initializers, this and module.exports assignments, which JSDoc comments count, and what .js allows that .ts does not.

jsconfig.json vs tsconfig.json

2026-10-21T00:00:00Z

The same file format with different defaults: what a jsconfig.json turns on by itself, how tsc and editors find each file, and when to use which.

JSDoc with TypeScript vs Flow

2026-10-21T00:00:00Z

Two ways to type JavaScript in comments: TypeScript's checker reading JSDoc, and Flow's comment types. Where each stands today, and how to move from Flow.

JSDoc-typed JavaScript vs Node's type stripping

2026-10-21T00:00:00Z

Node.js now runs .ts files by erasing their types. What that changes about the no-build-step argument, what it does not do, and which Node.js versions do it.

JSDoc-typed JavaScript vs TypeScript files

2026-10-21T00:00:00Z

The same checker reads both. What differs is syntax, the build step, and what each can express: a dated comparison with examples checked by tsc.

Migrating a JavaScript codebase to checked JavaScript, step by step

2026-10-21T00:00:00Z

Move an existing JavaScript project to type-checked JavaScript one step at a time: per file, per folder, then noImplicitAny and strict, measuring as you go.

Reading a TypeScript error message

2026-10-21T00:00:00Z

The parts of a tsc error: file, line and column, the TS code, message chains and related locations, and what --pretty and --explainFiles add.

Ship types from a JavaScript package

2026-10-21T00:00:00Z

Publish a JavaScript package with types: write .d.ts files from JSDoc, point exports at them, check them as a consumer, and keep CommonJS users working.

Should I use #private fields or @private in JavaScript?

2026-10-21T00:00:00Z

Private class members in checked JavaScript: #private fields that the runtime enforces, the @private JSDoc tag that only tsc enforces, and their errors.

The quirks of JSDoc in TypeScript

2026-10-21T00:00:00Z

The surprises of type-checked JavaScript, each with an example checked by tsc: comments that attach to nothing, tags that do less than they say, loose types.

TypeScript 5.9 vs 6.0 vs 7.0 for JavaScript projects

2026-10-21T00:00:00Z

What changes for checked JavaScript across TypeScript 5.9, 6.0 and the 7.0 native port: defaults, removed options, JSDoc 7.0 drops, speed, and an upgrade path.

What type does setTimeout return in JavaScript, Node.js or browser?

2026-10-21T00:00:00Z

setTimeout returns a number in browsers and a Timeout object in Node.js. Type timer handles in checked JavaScript with ReturnType.

Who checks JavaScript with JSDoc instead of writing TypeScript

2026-10-21T00:00:00Z

Svelte, SvelteKit, webpack, the unified collective, Lighthouse, Prettier and htmx check .js files with tsc: the evidence in each repository and their reasons.

Why does Object.keys return string[], and how do I keep the key type?

2026-10-21T00:00:00Z

Object.keys and Object.entries return string keys in TypeScript. Keep the key type in checked JavaScript with a @type cast or a small keysOf helper.

Runtime type checks vs static type annotations in JavaScript

2026-10-20T00:00:00Z

typeof and instanceof check values while code runs; TypeScript checks JSDoc-typed code before it runs. What each catches, and how they combine.

TypeScript 7.0 for JavaScript users

2026-07-08T00:00:00Z

TypeScript 7.0, the native port, for JavaScript: builds 8 to 12 times faster, and JSDoc is read like TypeScript, without @enum, @class or Closure types.

TypeScript 6.0 for JavaScript users

2026-03-23T00:00:00Z

TypeScript 6.0 for JavaScript: strict on and types empty by default, baseUrl and moduleResolution node deprecated, and the step before 7.0.

TypeScript 5.9 for JavaScript users

2025-08-01T00:00:00Z

TypeScript 5.9 for checked JavaScript: a shorter tsc --init, import defer, module node20, and a Uint8Array is no longer an ArrayBuffer.

TypeScript 5.8 for JavaScript users

2025-02-28T00:00:00Z

TypeScript 5.8 for checked JavaScript: each branch of a returned conditional is checked, require() of ES modules under nodenext, and no more assert.

TypeScript 5.7 for JavaScript users

2024-11-22T00:00:00Z

TypeScript 5.7 for checked JavaScript: variables nothing ever assigns, JSON imports need with { type: "json" } under nodenext, and es2024.

TypeScript 5.6 for JavaScript users

2024-09-09T00:00:00Z

TypeScript 5.6 for checked JavaScript: conditions that are always truthy are errors, iterator results under strict, and noUncheckedSideEffectImports.

TypeScript 5.5 for JavaScript users

2024-06-20T00:00:00Z

TypeScript 5.5 for checked JavaScript: the JSDoc @import tag, inferred type predicates, regular expression checks, and ${configDir}.

TypeScript 5.4 for JavaScript users

2024-03-06T00:00:00Z

TypeScript 5.4 for checked JavaScript: narrowing that survives into callbacks, the NoInfer type, Object.groupBy types, and module preserve.

TypeScript 5.3 for JavaScript users

2023-11-20T00:00:00Z

TypeScript 5.3 for checked JavaScript: import attributes, switch (true) narrowing, instanceof with Symbol.hasInstance, and super checks on fields.

TypeScript 5.2 for JavaScript users

2023-08-24T00:00:00Z

TypeScript 5.2 for checked JavaScript: using declarations, array methods on unions of arrays, .ts paths in import types, and matching module settings.

TypeScript 5.1 for JavaScript users

2023-06-01T00:00:00Z

TypeScript 5.1 for checked JavaScript: @returns {undefined} needs no return, unrelated getter and setter types, and @param snippets.

TypeScript 5.0 for JavaScript users

2023-03-16T00:00:00Z

TypeScript 5.0 for checked JavaScript: the @satisfies and @overload tags, @template const, extends with several configs, and moduleResolution bundler.

TypeScript 4.9 for JavaScript users

2022-11-15T00:00:00Z

TypeScript 4.9 for checked JavaScript: the in operator narrows unknown data, equality checks against not-a-number are errors, and emit keeps every import.

TypeScript 4.8 for JavaScript users

2022-08-25T00:00:00Z

TypeScript 4.8 for checked JavaScript: a @typedef can no longer be imported by name, comparing with [] is an error, and unknown narrows better.

TypeScript 4.7 for JavaScript users

2022-05-24T00:00:00Z

TypeScript 4.7 for checked JavaScript: Node.js ES module support with module nodenext, .mjs and .cjs files, package exports, and moduleDetection.

TypeScript 4.6 for JavaScript users

2022-02-28T00:00:00Z

TypeScript 4.6 for JavaScript: syntax and binding errors in every .js file, even unchecked ones, plus narrowing for destructured unions.

TypeScript 4.5 for JavaScript users

2021-11-17T00:00:00Z

TypeScript 4.5 for checked JavaScript: @type {const} and default @template arguments in JSDoc, the Awaited type, and #field in obj checks.

TypeScript 4.4 for JavaScript users

2021-08-26T00:00:00Z

TypeScript 4.4 for JavaScript: caught errors are unknown under strict, spelling suggestions in unchecked .js files, and checks stored in a const narrow.

TypeScript 4.3 for JavaScript users

2021-05-26T00:00:00Z

TypeScript 4.3 for checked JavaScript: setters that accept more types than their getters return, noImplicitOverride, {@link} in editors, and promise checks.

TypeScript 4.2 for JavaScript users

2021-02-23T00:00:00Z

TypeScript 4.2 for JavaScript: type arguments in a .js file parse as comparisons, untyped yield results are implicit any, and --explainFiles.

TypeScript 4.1 for JavaScript users

2020-11-19T00:00:00Z

TypeScript 4.1 for JavaScript: checkJs implies allowJs, @see in editors, noUncheckedIndexedAccess, and resolve() needs a value.

TypeScript 4.0 for JavaScript users

2020-08-20T00:00:00Z

TypeScript 4.0 for checked JavaScript: @deprecated in editors, ??= and ||=, variadic tuples in JSDoc, and delete needs an optional property.