Babel transpilation for Grunt

Common errors

• Error: Cannot find module '@babel/core'

  cause The `@babel/core` peer dependency is not installed.
  fix Run `npm install --save-dev @babel/core` or `yarn add --dev @babel/core`.

• Error: You have not specified any presets or plugins for babel.

  cause Babel requires at least one preset or plugin to perform transformations. The options are empty or misconfigured.
  fix Add a preset like `@babel/preset-env` to your `babel.options.presets` array: `presets: ['@babel/preset-env']`. Ensure the preset package is also installed.

• SyntaxError: 'import' and 'export' may only appear at the top level (when running outputted JS)

  cause The transpiled output still contains ES module syntax but is being run in an environment that expects CommonJS, likely because a preset like `@babel/preset-env` was configured not to transform modules.
  fix Ensure `@babel/preset-env` is configured to transform modules, e.g., `presets: [['@babel/preset-env', { modules: 'commonjs' }]]`.

Warnings

• breaking grunt-babel v8 requires Babel 7.x. Upgrading from v7 (Babel 6.x) requires updating all Babel related packages (e.g., `babel-core` to `@babel/core`, `babel-preset-env` to `@babel/preset-env`).
  Fix: Ensure all Babel packages are updated to their `@babel/` scoped versions (e.g., `npm install --save-dev @babel/core @babel/preset-env`) and configuration paths are adjusted accordingly.
• breaking Node.js v4 support was dropped in grunt-babel v8. Projects using older Node.js versions must remain on grunt-babel v7.
  Fix: Upgrade Node.js to a supported version (>=6.9 for grunt-babel v8), or explicitly install `grunt-babel@7` for Babel 6.x compatibility and Node.js v4-v5 support.
• breaking The `babel-core` package became a peerDependency in v7.0.0. Failure to install it will lead to runtime errors as `grunt-babel` cannot find the core transpiler.
  Fix: Manually install `@babel/core` (for v8+) or `babel-core` (for v7) in your project: `npm install --save-dev @babel/core`.
• gotcha Issues with transpilation output (e.g., incorrect syntax, missing polyfills) are generally problems with Babel itself, not `grunt-babel`. These should be reported to the Babel issue tracker.
  Fix: Verify your Babel configuration (presets, plugins) and report core transpilation issues on the official Babel GitHub repository.

Install

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

Imports

• babel
  wrong:

  import { babel } from 'grunt-babel';

  correct:

  grunt.initConfig({
    babel: { /* ... */ }
  });

  grunt-babel is a Grunt task, not a library for direct import. Its functionality is configured via `grunt.initConfig`.
• options
  wrong:

  const babelOptions = require('grunt-babel').options;

  correct:

  grunt.initConfig({
    babel: {
      options: { sourceMap: true, presets: ['@babel/preset-env'] },
      // ...
    }
  });

  Configuration options are passed directly within the Grunt task definition object, not imported.
• default task registration
  wrong:

  grunt.registerTask('babel', ['default']);

  correct:

  grunt.registerTask('default', ['babel']);

  This registers a Grunt task named 'default' that runs the 'babel' task. The `babel` task itself is implicitly registered by the plugin.

Quickstart

This quickstart configures grunt-babel to transpile 'src/app.js' into 'dist/app.js' using source maps and the '@babel/preset-env' preset, then registers it as the default Grunt task.

require('load-grunt-tasks')(grunt); // npm install --save-dev load-grunt-tasks

grunt.initConfig({
  babel: {
    options: {
      sourceMap: true,
      presets: ['@babel/preset-env'] // Ensure @babel/preset-env is installed
    },
    dist: {
      files: {
        'dist/app.js': 'src/app.js'
      }
    }
  }
});

grunt.registerTask('default', ['babel']);