{"id":19089,"library":"babel-plugin-jsdoc-to-assert","title":"babel-plugin-jsdoc-to-assert","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/azu/babel-plugin-jsdoc-to-assert","tags":["javascript","babel","plugin","assert","testing","coc"],"install":[{"cmd":"npm install babel-plugin-jsdoc-to-assert","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-jsdoc-to-assert","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-jsdoc-to-assert","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for Babel 7 plugin","package":"@babel/core","optional":true}],"imports":[{"note":"This is a Babel plugin; it is used declaratively in .babelrc or babel.config.js, not imported directly into application code.","wrong":"import plugin from 'babel-plugin-jsdoc-to-assert'","symbol":"default","correct":"module.exports = require('babel-plugin-jsdoc-to-assert')"},{"note":"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.","wrong":"\"plugins\": [\"babel-plugin-jsdoc-to-assert\"]","symbol":"jsdoc-to-assert plugin name","correct":"\"plugins\": [\"jsdoc-to-assert\"]"},{"note":"Options must be passed as the second element of an array within the plugins array. Incorrect nesting will cause options to be ignored.","wrong":"\"plugins\": [\"jsdoc-to-assert\", { \"checkAtType\": true }]","symbol":"options","correct":"\"plugins\": [[\"jsdoc-to-assert\", { \"checkAtType\": true }]]"}],"quickstart":{"code":"// .babelrc\n{\n  \"plugins\": [\"jsdoc-to-assert\"],\n  \"env\": {\n    \"development\": {\n      \"plugins\": [\"jsdoc-to-assert\"]\n    }\n  }\n}\n\n// Source file (src/index.js)\n/**\n * Adds two numbers.\n * @param {number} a - first number\n * @param {number} b - second number\n * @returns {number} sum\n */\nfunction add(a, b) {\n  return a + b;\n}\n\n// Build script (package.json)\n\"scripts\": {\n  \"build\": \"NODE_ENV=production babel src --out-dir lib --source-maps\"\n}\n\n// After transform (development build): function add(a, b) { console.assert(typeof a === 'number'); console.assert(typeof b === 'number'); return a + b; }\n","lang":"javascript","description":"Shows .babelrc configuration, environment-specific usage, and the runtime assertion transformation for @param types."},"warnings":[{"fix":"Upgrade to Babel 7 and ensure @babel/core is installed.","message":"v4.0.0 drops Babel 6 support; requires Babel 7 or later.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Set checkAtType: true only if plugin runs before ES2015 transforms (e.g., via plugin ordering). Consider using babel-preset-jsdoc-to-assert.","message":"checkAtType is disabled by default because ES2015 transforms may run before this plugin, causing AssertionError with incorrect variable names (e.g., typeof _this === 'string').","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use babel-preset-jsdoc-to-assert with useSpecReporter option for throwing assertions.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade to v4.0.0 for Babel 7 compatibility.","message":"v3.x and earlier used jsdoc-to-assert internally; v4.0.0 may have updated dependencies.","severity":"deprecated","affected_versions":"<4.0.0"},{"fix":"Ensure source files are syntactically valid JavaScript. If error persists, file an issue with code sample.","message":"The plugin may fail on files with syntax errors (e.g., unterminated string constants). Reported as SyntaxError during babel build.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Fix the syntax error in the source file. If the error is not reproducible without the plugin, file an issue on GitHub.","cause":"The plugin encounters a file with a syntax error (unterminated string) during transformation.","error":"ERROR in ./src/js/framework/Context.js\nModule build failed: SyntaxError: Unterminated string constant (3:16)"},{"fix":"Disable checkAtType or use babel-preset-jsdoc-to-assert which handles ordering. Alternatively, ensure plugin runs after ES2015 transforms.","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.","error":"AssertionError: Invalid JSDoc: typeof _this === 'string'"},{"fix":"Polyfill console or consider using babel-preset-jsdoc-to-assert with useSpecReporter which uses assert instead.","cause":"Using the plugin in an environment where console is not available (e.g., some older Web Workers or strict CSP).","error":"ReferenceError: console is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}