Boost JavaScript Type Safety in VS Code with JSDoc Annotations

Developers often assume that TypeScript or Flow are required for JavaScript type safety, but this article shows how to achieve similar checks directly in Visual Studio Code using JSDoc annotations. By adding JSDoc comments and enabling checkJs in VS Code, the editor provides IntelliSense, hover tooltips, and error highlighting based on inferred types.

Why Use Type Checking

Types give valuable information about code, help catch spelling errors early, aid refactoring, improve readability, and provide intelligent code completion. These benefits are available whether you use TypeScript, Flow, or JSDoc.

Enabling JSDoc Type Checking in VS Code

Open the command palette ( Ctrl+Shift+P) and edit settings.json to add:

{
  "javascript.implicitProjectConfig.checkJs": true
}

After saving, VS Code underlines type errors with red squiggles and shows detailed messages on hover.

Alternative Per‑File Controls

Add // @ts-check at the top of a file to enable checking for that file only.

Add // @ts-nocheck to disable checking for a specific file.

Use // @ts-ignore to silence a single error.

Defining Types with JSDoc

JSDoc provides standard tags that are interpreted by the TypeScript language service: @type {string} – simple type annotation. @typedef – creates a custom type similar to a TypeScript interface. @property – describes object members. @param and @return – document function signatures. @template – defines generic parameters. @type casting – /** @type {Element} */ (elem) tells the checker to treat a value as a specific type.

Examples include annotating a string variable, defining union types ( number | string), intersection types, optional properties using [], and complex object shapes.

Working with Dynamic (Expando) Properties

Static analysis cannot infer properties added after object creation. Use bracket notation with quoted keys (e.g., obj['newProp'] = true) to avoid type‑error warnings.

Importing Types Across Files

Export custom JSDoc types from one module and import them elsewhere using TypeScript’s import() syntax in a comment, e.g., /** @typedef {import('./vnode').VNode} VNode */.

Running Type Checks in Build Scripts

Add an npm script:

"scripts": {
  "checkjs": "tsc --allowJs --checkJs --noEmit --target ES5 src/*.js"
}

Running npm run checkjs reports type errors with line numbers.

Runtime Type Safety

Static checks do not guarantee runtime safety. Use explicit type guards (e.g., if (typeof value === 'string')) and log or handle mismatched types. Type casting can be used when the developer knows a value’s actual type.

Summary

JSDoc in VS Code offers most TypeScript benefits without a compilation step.

Configure checkJs globally or per file.

Define simple, union, intersection, generic, and optional types with JSDoc tags.

Handle dynamic properties via bracket notation.

Import and reuse custom types across modules.

Run type checks in CI using an npm script.

Complement static analysis with runtime guards for full safety.

By adopting JSDoc annotations, JavaScript teams can improve code quality, onboarding, and maintainability while keeping the code runnable in browsers without extra build steps.