jsdoc-babel

0.5.0 verified Sat Apr 25 auth: no javascript maintenance

jsdoc-babel is a JSDoc plugin that transforms ES6+ source files with Babel before JSDoc processes them. At version 0.5.0, it allows JSDoc to handle unsupported syntax (e.g., modern JavaScript, Flow, TypeScript) by leveraging Babel's transpilation pipeline. The plugin is lightweight, requires only @babel/core as a peer dependency, and integrates via JSDoc's configuration. It supports custom file extensions (default .js) and allows Babel options to be passed directly in the JSDoc config or via .babelrc. Compared to alternatives like jsdoc-babel-only, it is simpler and more directly tied to Babel 7+.

Common errors

error Error: JSDoc plugin "node_modules/jsdoc-babel" failed to load: Cannot find module '@babel/core' ↓

cause @babel/core is a peer dependency; not installed.

fix

Run 'npm install @babel/core --save-dev' to install the peer dependency.

error Error: Unable to parse source file: ... You may need an appropriate loader to handle this file type. ↓

cause JSDoc cannot parse a non-.js file because the plugin's extensions list does not include that file's extension.

fix

Add the file extension to the 'babel.extensions' array in JSDoc config.

error JSDoc reports no documented source files. ↓

cause Plugin transforms fail silently, leaving files unparsed because .babelrc is ignored or misconfigured.

fix

Ensure 'babel' config in JSDoc includes required presets (e.g., '@babel/preset-env') and set 'babelrc': false if you rely solely on JSDoc config.

Warnings

gotcha Plugin only processes files with .js extension by default. Files with other extensions (e.g., .es6, .jsx) will not be transformed unless you add them to the 'babel.extensions' array. ↓

fix Add the desired extensions to the 'babel.extensions' array in your JSDoc configuration.

gotcha Options defined in JSDoc config take precedence over those in .babelrc. Unexpected merging behavior can occur if both are present. ↓

fix Set 'babelrc': false in JSDoc config to disable .babelrc resolution, or ensure no conflicting options.

deprecated The plugin uses the older Babel 7 API (babel.transform), which may not support newer Babel 7.x features or preset syntax. Future Babel versions might break compatibility. ↓

fix Monitor for updates or consider using JSDoc's built-in Babylon parser if you do not need Babel transforms.

Install

npm install jsdoc-babel

yarn add jsdoc-babel

pnpm add jsdoc-babel

Imports

jsdoc-babel plugin
wrong
```
import jsdocBabel from 'jsdoc-babel'
```
correct
```
Use the string 'node_modules/jsdoc-babel' in JSDoc config's plugins array.
```
This is a JSDoc plugin, not a regular npm module. It is loaded by JSDoc at runtime via configuration, not by import/require.

Babel options

wrong

Using .babelrc without overriding in JSDoc config - options merge may cause conflicts.

correct

Add 'babel' key to JSDoc config JSON. Example: { 'plugins': ['node_modules/jsdoc-babel'], 'babel': { 'presets': ['@babel/env'] } }

Options defined in JSDoc config take precedence over .babelrc. Set 'babelrc': false to disable .babelrc resolution.

File extensions

wrong

Assuming all file extensions are processed automatically.

correct

Specify 'babel.extensions' array in JSDoc config to include additional extensions like 'es6', 'jsx'.

Default extension is only '.js'. Add custom extensions explicitly.

Quickstart

JSDoc configuration that enables the plugin, processes .es6 and .jsx files, and passes Babel options directly (ignoring .babelrc).

{
  "plugins": ["node_modules/jsdoc-babel"],
  "babel": {
    "extensions": ["js", "es6", "jsx"],
    "presets": ["@babel/preset-env"],
    "babelrc": false
  }
}