Grunt: The JavaScript Task Runner

Common errors

• Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: Gruntfile.js

  cause Attempting to use ES module syntax (e.g., `import` or `export`) in `Gruntfile.js` or directly imported files, which Grunt does not natively support for its configuration files.
  fix Rewrite `Gruntfile.js` and any directly loaded custom task files to use CommonJS syntax (`module.exports = function(grunt) { ... };` and `require()`). Ensure `package.json` does not have `"type": "module"` if Grunt is the primary runner.

• grunt: command not found

  cause The `grunt-cli` package, which provides the `grunt` executable, is either not installed or not available in your system's PATH.
  fix Install `grunt-cli` globally: `npm install -g grunt-cli`. Ensure your system's PATH includes npm global binaries. Alternatively, if installed locally, run `npx grunt` or add `./node_modules/.bin/grunt` to your PATH.

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

  cause The specified task was not registered in the `Gruntfile.js`, or the plugin providing it was not loaded, or there's a typo in the task name.
  fix Verify that `grunt.registerTask('mytask', ...)` has been called, or if it's from a plugin, that `grunt.loadNpmTasks('grunt-contrib-mytask');` has been correctly used and the plugin is installed in `devDependencies`.

Warnings

• breaking Gruntfiles are traditionally CommonJS modules (using `module.exports`). Attempting to use ES Modules syntax (`import`/`export`) directly in your `Gruntfile.js` will likely result in a `ERR_REQUIRE_ESM` error. While Node.js supports ESM, Grunt itself does not natively support ESM Gruntfiles without transpilation or specific workarounds.
  Fix: Ensure your `Gruntfile.js` uses CommonJS syntax (`module.exports = function(grunt) { ... };`). If you need to use ESM in custom tasks, you might need to transpile them or use dynamic `import()` within a CJS Gruntfile.
• gotcha Only the latest minor version of Grunt is actively supported for security and bug fixes. Older versions are considered end-of-life (EOL). Using EOL versions means you will not receive official updates for vulnerabilities or issues.
  Fix: Regularly update to the latest stable minor version of Grunt (currently 1.6.x). If maintaining older projects, consider commercial support options like those offered by HeroDevs mentioned in the official documentation.
• breaking Grunt 1.6.1 removed internal dependencies on `rimraf` and `mkdirp`. While this primarily affects internal implementation, if any Grunt plugins or custom tasks were implicitly relying on `grunt.file` methods that previously delegated to these, there could be subtle behavioral changes.
  Fix: Review custom tasks and plugin implementations to ensure they are not making assumptions about underlying file system utility behavior that might have changed with internal dependency removal. Test thoroughly after upgrading.
• breaking Grunt 1.6.0 bumped the minimum required Node.js version to `Node.js >=16`. Running Grunt on older Node.js environments will lead to errors.
  Fix: Ensure your development and build environments use Node.js version 16 or newer. Update Node.js if necessary.

Install

• npm install grunt npm
• yarn add grunt yarn
• pnpm add grunt pnpm

Imports

• grunt object in Gruntfile.js
  wrong:

  import { initConfig } from 'grunt';
  const grunt = require('grunt');

  correct:

  module.exports = function(grunt) { /* ... */ };

  The core 'grunt' package is not typically imported directly into user application code. Instead, the 'grunt' object, which contains all the API methods, is passed as an argument to the function exported by your Gruntfile.js. Gruntfiles are generally CommonJS modules.
• grunt.initConfig

  module.exports = function(grunt) {
    grunt.initConfig({
      pkg: grunt.file.readJSON('package.json'),
      uglify: { /* ... */ }
    });
  };

  Used within a Gruntfile.js to define project and task-specific configuration. It's the primary way to configure tasks and access project metadata.
• grunt.loadNpmTasks

  module.exports = function(grunt) {
    // ...
    grunt.loadNpmTasks('grunt-contrib-uglify');
  };

  Loads tasks from installed Grunt plugins. This makes the tasks available for configuration and execution within your Gruntfile.js.

Quickstart

This quickstart demonstrates a basic Grunt setup, including `package.json` for dependencies and a `Gruntfile.js` to define tasks for JavaScript minification and file watching. After `npm install`, running `grunt` executes the default `uglify` task, while `grunt dev` will minify and then watch for changes.

{
  "name": "my-project",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "^1.6.0",
    "grunt-contrib-uglify": "^5.0.0",
    "grunt-contrib-watch": "^1.1.0"
  }
}

// Gruntfile.js
module.exports = function(grunt) {

  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      build: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'dist/<%= pkg.name %>.min.js'
      }
    },
    watch: {
      scripts: {
        files: ['src/**/*.js'],
        tasks: ['uglify'],
        options: {
          spawn: false,
        },
      },
    },
  });

  grunt.loadNpmTasks('grunt-contrib-uglify');
  grunt.loadNpmTasks('grunt-contrib-watch');

  grunt.registerTask('default', ['uglify']);
  grunt.registerTask('dev', ['default', 'watch']);
};