babel-plugin-jsdoc-to-assert

4.0.0 verified Sat Apr 25 auth: no javascript

A Babel plugin that converts JSDoc type annotations (@param and @type) into runtime assertion statements (console.assert) for testing. Version 4.0.0 is the current stable release, requiring Babel 7+. The plugin transforms static type documentation into executable checks, enabling runtime verification without a separate type system. Unlike TypeScript or Flow, it operates at the AST level during Babel transpilation and supports generic arrays (e.g., number[]) and rest parameters. Its primary differentiator is seamless integration into Babel workflows for development-only assertions, with options to enable/disable @param and @type checking. The package is maintained by azu and has a preset version (babel-preset-jsdoc-to-assert). Releases are infrequent, focusing on compatibility and bug fixes.

Common errors

error ERROR in ./src/js/framework/Context.js Module build failed: SyntaxError: Unterminated string constant (3:16) ↓

cause The plugin encounters a file with a syntax error (unterminated string) during transformation.

fix

Fix the syntax error in the source file. If the error is not reproducible without the plugin, file an issue on GitHub.

error AssertionError: Invalid JSDoc: typeof _this === 'string' ↓

cause checkAtType is enabled and the ES2015 arrow function transform (which renames 'this' to '_this') runs after jsdoc-to-assert, causing the generated assertion to use the incorrect variable name.

fix

Disable checkAtType or use babel-preset-jsdoc-to-assert which handles ordering. Alternatively, ensure plugin runs after ES2015 transforms.

error ReferenceError: console is not defined ↓

cause Using the plugin in an environment where console is not available (e.g., some older Web Workers or strict CSP).

fix

Polyfill console or consider using babel-preset-jsdoc-to-assert with useSpecReporter which uses assert instead.

Warnings

breaking v4.0.0 drops Babel 6 support; requires Babel 7 or later. ↓

fix Upgrade to Babel 7 and ensure @babel/core is installed.

gotcha checkAtType is disabled by default because ES2015 transforms may run before this plugin, causing AssertionError with incorrect variable names (e.g., typeof _this === 'string'). ↓

fix Set checkAtType: true only if plugin runs before ES2015 transforms (e.g., via plugin ordering). Consider using babel-preset-jsdoc-to-assert.

gotcha Plugin uses console.assert, which does not throw on failure in Node.js (only prints to stderr). For test frameworks, use babel-preset-jsdoc-to-assert with useSpecReporter. ↓

fix Use babel-preset-jsdoc-to-assert with useSpecReporter option for throwing assertions.

deprecated v3.x and earlier used jsdoc-to-assert internally; v4.0.0 may have updated dependencies. ↓

fix Upgrade to v4.0.0 for Babel 7 compatibility.

gotcha The plugin may fail on files with syntax errors (e.g., unterminated string constants). Reported as SyntaxError during babel build. ↓

fix Ensure source files are syntactically valid JavaScript. If error persists, file an issue with code sample.

Install

npm install babel-plugin-jsdoc-to-assert

yarn add babel-plugin-jsdoc-to-assert

pnpm add babel-plugin-jsdoc-to-assert

Imports

default
wrong
```
import plugin from 'babel-plugin-jsdoc-to-assert'
```
correct
```
module.exports = require('babel-plugin-jsdoc-to-assert')
```
This is a Babel plugin; it is used declaratively in .babelrc or babel.config.js, not imported directly into application code.
jsdoc-to-assert plugin name
wrong
```
"plugins": ["babel-plugin-jsdoc-to-assert"]
```
correct
```
"plugins": ["jsdoc-to-assert"]
```
In .babelrc or babel.config.js, the plugin name is 'jsdoc-to-assert', not the full npm package name. The 'babel-plugin-' prefix is implied.
options
wrong
```
"plugins": ["jsdoc-to-assert", { "checkAtType": true }]
```
correct
```
"plugins": [["jsdoc-to-assert", { "checkAtType": true }]]
```
Options must be passed as the second element of an array within the plugins array. Incorrect nesting will cause options to be ignored.

Quickstart

Shows .babelrc configuration, environment-specific usage, and the runtime assertion transformation for @param types.

// .babelrc
{
  "plugins": ["jsdoc-to-assert"],
  "env": {
    "development": {
      "plugins": ["jsdoc-to-assert"]
    }
  }
}

// Source file (src/index.js)
/**
 * Adds two numbers.
 * @param {number} a - first number
 * @param {number} b - second number
 * @returns {number} sum
 */
function add(a, b) {
  return a + b;
}

// Build script (package.json)
"scripts": {
  "build": "NODE_ENV=production babel src --out-dir lib --source-maps"
}

// After transform (development build): function add(a, b) { console.assert(typeof a === 'number'); console.assert(typeof b === 'number'); return a + b; }