grunt-jsdoc

library2.4.1jsnpmunverified

grunt-jsdoc is a Grunt plugin designed to integrate JSDoc 3 documentation generation directly into a Grunt build process. It acts as a wrapper around the JSDoc tool, allowing developers to define documentation sources and output destinations within their Gruntfile.js. The current stable version is 2.4.1. Releases are infrequent, typically occurring to update the underlying JSDoc dependency (e.g., for security patches) or address minor compatibility issues. Its key differentiator is its tight integration into the Grunt ecosystem, providing a task-runner-centric approach to documentation, as opposed to running JSDoc directly from the command line or using a different build tool.

devops

npm install grunt-jsdoc

github ↗package ↗

INSTALL

IMPORT

SIG · GRUNT-JSDOC

grunt-jsdoc

devopsjavascriptv2.4.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loadNpmTasks

✓ grunt.loadNpmTasks('grunt-jsdoc');

✗ import { jsdoc } from 'grunt-jsdoc';

Grunt plugins are loaded via `grunt.loadNpmTasks` in the Gruntfile, not standard ES module imports.

jsdoc task configuration

✓ grunt.initConfig({ jsdoc: { dist: { src: ['src/*.js'], options: { destination: 'doc' } } } });

The 'jsdoc' property within `grunt.initConfig` defines the task's behavior and options.

Calling the task

✓ grunt.registerTask('default', ['jsdoc']);

✗ require('grunt-jsdoc').run();

The task is executed via the Grunt CLI (`grunt jsdoc`) or as part of a registered Grunt task.

This quickstart demonstrates how to configure and run the `grunt-jsdoc` task, including how to use an external JSDoc template like `ink-docstrap`. It shows a complete `Gruntfile.js` and a basic JavaScript file with JSDoc comments for generation.

/* Gruntfile.js */ module.exports = function(grunt) { // Project configuration. grunt.initConfig({ pkg: grunt.file.readJSON('package.json'), jsdoc : { dist : { src: ['src/**/*.js', 'README.md'], jsdoc: './node_modules/.bin/jsdoc', options: { destination: 'doc', template: 'node_modules/ink-docstrap/template', configure: 'node_modules/ink-docstrap/template/jsdoc.conf.json', encoding: 'utf8' } } } }); // Load the plugin that provides the 'jsdoc' task. grunt.loadNpmTasks('grunt-jsdoc'); // Default task(s). grunt.registerTask('default', ['jsdoc']); }; /* src/example.js */ /** * @module MyModule * Represents a simple example class. */ class MyClass { /** * Creates an instance of MyClass. * @param {string} name - The name of the instance. */ constructor(name) { /** @private */ this._name = name; } /** * Greets the given person. * @param {string} person - The person to greet. * @returns {string} A greeting message. */ greet(person) { return `Hello, ${person}! My name is ${this._name}.`; } } module.exports = MyClass;

Debug

Known issues

breakingThe direct dependency on `ink-docstrap` was removed in version 1.0.0. Users upgrading from 0.x.x to 1.x.x or newer must explicitly install `ink-docstrap` if they intend to use it as a JSDoc template.

fix

Install `ink-docstrap` separately: `npm install --save-dev ink-docstrap`.

affects: >=1.0.0

breakingIn version 2.0.0, the `private` option for JSDoc now follows JSDoc's default behavior, which means it is `false` by default. This change might hide documentation for private members if not explicitly configured.

fix

Review JSDoc configurations for `private` option usage and set it explicitly to `true` if private members should be documented.

affects: >=2.0.0

gotchaNode.js version requirements have increased over time. As of v2.4.1, Node.js >= 8.12.0 is required. Older Node.js versions may not be compatible, leading to build failures.

fix

Ensure your Node.js environment meets the minimum requirement specified in the package's `engines` field (currently `'>= 8.12.0'`).

affects: >=2.4.0

gotchaThe `jsdoc` option allows specifying the path to the JSDoc executable. While often not needed, in some environments or complex setups, the `grunt-jsdoc` plugin might struggle to locate the correct JSDoc binary. This can lead to JSDoc not running or running with an incorrect version.

fix

Explicitly set the `jsdoc` option in your Gruntfile to the full path of the JSDoc executable, e.g., `jsdoc: './node_modules/.bin/jsdoc'`.

affects: >=1.0.0

gotchaSecurity updates to underlying dependencies like JSDoc or `marked` (a transitive dependency) are crucial. `grunt-jsdoc` v2.4.0 updated to JSDoc 3.6.0 for a security fix, and v2.3.1/v2.2.1 addressed regex DoS and XSS vulnerabilities in `marked` respectively. Running older versions could expose projects to these issues.

fix

Always keep `grunt-jsdoc` updated to the latest stable version to benefit from security patches in its dependencies.

affects: <2.4.0

Errors

Common errors & fixes

Warning: Task "jsdoc" not found. Use --force to continue.

The Grunt plugin `grunt-jsdoc` has not been loaded in the Gruntfile.

fix

Add `grunt.loadNpmTasks('grunt-jsdoc');` to your Gruntfile.js.

Error: Cannot find module 'ink-docstrap/template'

The `ink-docstrap` package is specified as a JSDoc template but is not installed or incorrectly referenced.

fix

Ensure `ink-docstrap` is installed (`npm install --save-dev ink-docstrap`) and the `template` and `configure` paths in your Gruntfile configuration correctly point to `node_modules/ink-docstrap/template`.

Fatal error: The 'destination' property is required in your jsdoc options. See the jsdoc documentation.

The `destination` option, which specifies where the documentation will be generated, is missing from the `jsdoc` task configuration.

fix

Add `destination: 'path/to/doc'` within the `options` object of your `jsdoc` task configuration in Gruntfile.js.

Error: spawn ENOENT

The JSDoc executable cannot be found by `grunt-jsdoc`, often due to environment path issues or missing JSDoc installation.

fix

Explicitly set the `jsdoc` option to the path of the JSDoc binary, typically `jsdoc: './node_modules/.bin/jsdoc'`, or ensure JSDoc is correctly installed as a dependency.

Upgrade

Version history

2.4.1latest on npm

Audit

Dependencies

gruntrequiredPeer dependency, required to run the Grunt task.

jsdocrequiredCore dependency, grunt-jsdoc wraps its functionality for documentation generation.

ink-docstrapoptionalOptional dependency for using the Ink-Docstrap template with JSDoc.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/krampstudio/grunt-jsdoc ↗

packagehttps://www.npmjs.com/package/grunt-jsdoc ↗