Grunt Rollup Plugin

Common errors

• TypeError: (0 , _pluginBabel.default) is not a function

  cause Incorrectly importing a scoped Rollup plugin (like `@rollup/plugin-babel`) in a CommonJS Gruntfile, missing the `.default` property.
  fix Use `const plugin = require('@rollup/plugin-name').default;` to correctly access the plugin's main function from scoped packages within a CommonJS environment.

• Error: [!] RollupError: Could not resolve 'module-name' from 'path/to/file.js'

  cause Rollup cannot find an imported module, often because the module is not installed or the `@rollup/plugin-node-resolve` is missing from the plugins array.
  fix First, ensure all project dependencies are installed (`npm install`). Then, include `@rollup/plugin-node-resolve` in your `options.plugins` array within `Gruntfile.js` to enable Node.js style module resolution.

• Warning: Task "rollup" failed. Use --force to continue.

  cause A general Grunt task failure, typically indicating underlying configuration errors in the Rollup setup, such as invalid options, non-existent entry files, or issues with Rollup plugins.
  fix Run Grunt with verbose logging (`grunt rollup --verbose`) to reveal the detailed Rollup error messages, which will pinpoint the exact issue in your `Gruntfile.js` or Rollup configuration.

• ReferenceError: grunt is not defined

  cause The `Gruntfile.js` is not correctly structured, or the `grunt-rollup` plugin (or Grunt itself) has not been properly initialized or loaded.
  fix Ensure your `Gruntfile.js` adheres to the standard Grunt structure: `module.exports = function(grunt) { ... };` and that `grunt.loadNpmTasks('grunt-rollup');` is called within this function.

Warnings

• breaking The `namespaceToStringTag` output option has been removed in Rollup v2.71.1.
  Fix: Replace `namespaceToStringTag` with the new `output.generatedCode.symbols` option to configure `Symbol.toStringTag` generation. Refer to the Rollup documentation for usage details.
• breaking The `dynamicImportFunction` option has been deprecated, and options like `inlineDynamicImports`, `manualChunks`, and `preserveModules` have been moved to the `output` configuration object.
  Fix: Remove `dynamicImportFunction`. Migrate `inlineDynamicImports`, `manualChunks`, and `preserveModules` into the `output` object within your Rollup task options. Consult Rollup's v2 documentation for updated usage.
• breaking Version 11.0.0 updated the underlying Rollup dependency to v2.x. This introduced significant breaking changes within Rollup itself.
  Fix: Carefully review the official Rollup v2 migration guide for any breaking changes in Rollup's core configuration, API, or plugin ecosystem that might affect your project's build process.
• gotcha Some Rollup plugins are stateful (e.g., keeping track of used Babel helpers) and can cause unexpected behavior when reused across multiple bundles in a single 'grunt-rollup' task.
  Fix: To ensure a fresh plugin instance for each bundle, pass a function that returns an array of plugins to the `options.plugins` property (e.g., `plugins: function() { return [babel({...})]; }`).
• gotcha The `package.json` for `grunt-rollup` specifies a minimum Node.js version of `>=12`, which is higher than what older `README.md` versions might state (`>=8.6.0`).
  Fix: Ensure your Node.js environment is version 12 or higher to meet the current compatibility requirements of `grunt-rollup` and its dependencies.

Install

• npm install grunt-rollup npm
• yarn add grunt-rollup yarn
• pnpm add grunt-rollup pnpm

Imports

• grunt.loadNpmTasks
  wrong:

  import rollup from 'grunt-rollup';

  correct:

  grunt.loadNpmTasks('grunt-rollup');

  grunt-rollup is a Grunt plugin loaded via grunt.loadNpmTasks in your Gruntfile.js, not a direct JavaScript module for import or require.
• babel
  wrong:

  import babel from '@rollup/plugin-babel';

  correct:

  const babel = require('@rollup/plugin-babel').default;

  Gruntfile.js is typically CommonJS. Many scoped Rollup plugins like @rollup/plugin-babel export their main function as a .default property when required for CommonJS compatibility.
• commonjs
  wrong:

  import commonjs from '@rollup/plugin-commonjs';

  correct:

  const commonjs = require('@rollup/plugin-commonjs');

  For non-scoped or simpler Rollup plugins, a direct require() typically suffices. Remember to install any Rollup plugins separately via npm.

Quickstart

This quickstart demonstrates how to configure 'grunt-rollup' in a Gruntfile.js, including setting up basic Rollup options, integrating the `@rollup/plugin-babel`, and correctly handling stateful plugins with a function for multiple output bundles.

const babel = require('@rollup/plugin-babel').default;

module.exports = function(grunt) {
  grunt.initConfig({
    rollup: {
      options: {
        // Common Rollup output options, often recommended to be explicit
        output: {
          format: 'es', // or 'cjs', 'umd', 'iife'
          sourcemap: true
        },
        // Use a function to return plugins for stateful plugins or multiple bundles
        plugins: function() {
          return [
            babel({
              babelHelpers: 'bundled',
              exclude: './node_modules/**' // Exclude node_modules to speed up transpilation
            })
            // Add other Rollup plugins here, e.g., require('@rollup/plugin-node-resolve').default()
          ];
        }
      },
      // Define multiple targets/bundles
      app: {
        files: {
          'dest/bundle.js': 'src/entry.js' // Bundle src/entry.js into dest/bundle.js
        }
      },
      anotherApp: {
        files: {
          'dest/bundle2.js': 'src/entry2.js' // Bundle src/entry2.js into dest/bundle2.js
        }
      }
    }
  });

  // Load the grunt-rollup plugin
  grunt.loadNpmTasks('grunt-rollup');

  // Register a default task to run rollup
  grunt.registerTask('default', ['rollup']);
};