{"id":15634,"library":"grunt-jsdoc","title":"JSDoc Integration for Grunt","description":"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.","status":"maintenance","version":"2.4.1","language":"javascript","source_language":"en","source_url":"git://github.com/krampstudio/grunt-jsdoc","tags":["javascript","gruntplugin","grunt","documentation","doc","jsdoc","jsdoc3"],"install":[{"cmd":"npm install grunt-jsdoc","lang":"bash","label":"npm"},{"cmd":"yarn add grunt-jsdoc","lang":"bash","label":"yarn"},{"cmd":"pnpm add grunt-jsdoc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required to run the Grunt task.","package":"grunt","optional":false},{"reason":"Core dependency, grunt-jsdoc wraps its functionality for documentation generation.","package":"jsdoc","optional":false},{"reason":"Optional dependency for using the Ink-Docstrap template with JSDoc.","package":"ink-docstrap","optional":true}],"imports":[{"note":"Grunt plugins are loaded via `grunt.loadNpmTasks` in the Gruntfile, not standard ES module imports.","wrong":"import { jsdoc } from 'grunt-jsdoc';","symbol":"loadNpmTasks","correct":"grunt.loadNpmTasks('grunt-jsdoc');"},{"note":"The 'jsdoc' property within `grunt.initConfig` defines the task's behavior and options.","symbol":"jsdoc task configuration","correct":"grunt.initConfig({ jsdoc: { dist: { src: ['src/*.js'], options: { destination: 'doc' } } } });"},{"note":"The task is executed via the Grunt CLI (`grunt jsdoc`) or as part of a registered Grunt task.","wrong":"require('grunt-jsdoc').run();","symbol":"Calling the task","correct":"grunt.registerTask('default', ['jsdoc']);"}],"quickstart":{"code":"/* Gruntfile.js */\nmodule.exports = function(grunt) {\n\n  // Project configuration.\n  grunt.initConfig({\n    pkg: grunt.file.readJSON('package.json'),\n    jsdoc : {\n        dist : {\n            src: ['src/**/*.js', 'README.md'],\n            jsdoc: './node_modules/.bin/jsdoc',\n            options: {\n                destination: 'doc',\n                template: 'node_modules/ink-docstrap/template',\n                configure: 'node_modules/ink-docstrap/template/jsdoc.conf.json',\n                encoding: 'utf8'\n            }\n        }\n    }\n  });\n\n  // Load the plugin that provides the 'jsdoc' task.\n  grunt.loadNpmTasks('grunt-jsdoc');\n\n  // Default task(s).\n  grunt.registerTask('default', ['jsdoc']);\n\n};\n\n/* src/example.js */\n/**\n * @module MyModule\n * Represents a simple example class.\n */\nclass MyClass {\n  /**\n   * Creates an instance of MyClass.\n   * @param {string} name - The name of the instance.\n   */\n  constructor(name) {\n    /** @private */\n    this._name = name;\n  }\n\n  /**\n   * Greets the given person.\n   * @param {string} person - The person to greet.\n   * @returns {string} A greeting message.\n   */\n  greet(person) {\n    return `Hello, ${person}! My name is ${this._name}.`;\n  }\n}\n\nmodule.exports = MyClass;\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Install `ink-docstrap` separately: `npm install --save-dev ink-docstrap`.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Review JSDoc configurations for `private` option usage and set it explicitly to `true` if private members should be documented.","message":"In 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js environment meets the minimum requirement specified in the package's `engines` field (currently `'>= 8.12.0'`).","message":"Node.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.","severity":"gotcha","affected_versions":">=2.4.0"},{"fix":"Explicitly set the `jsdoc` option in your Gruntfile to the full path of the JSDoc executable, e.g., `jsdoc: './node_modules/.bin/jsdoc'`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always keep `grunt-jsdoc` updated to the latest stable version to benefit from security patches in its dependencies.","message":"Security 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.","severity":"gotcha","affected_versions":"<2.4.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Add `grunt.loadNpmTasks('grunt-jsdoc');` to your Gruntfile.js.","cause":"The Grunt plugin `grunt-jsdoc` has not been loaded in the Gruntfile.","error":"Warning: Task \"jsdoc\" not found. Use --force to continue."},{"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`.","cause":"The `ink-docstrap` package is specified as a JSDoc template but is not installed or incorrectly referenced.","error":"Error: Cannot find module 'ink-docstrap/template'"},{"fix":"Add `destination: 'path/to/doc'` within the `options` object of your `jsdoc` task configuration in Gruntfile.js.","cause":"The `destination` option, which specifies where the documentation will be generated, is missing from the `jsdoc` task configuration.","error":"Fatal error: The 'destination' property is required in your jsdoc options. See the jsdoc documentation."},{"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.","cause":"The JSDoc executable cannot be found by `grunt-jsdoc`, often due to environment path issues or missing JSDoc installation.","error":"Error: spawn ENOENT"}],"ecosystem":"npm"}