{"id":10977,"library":"grunt-babel","title":"Babel transpilation for Grunt","description":"grunt-babel is a Grunt plugin that integrates Babel, allowing developers to transpile modern JavaScript code (ESNext) into backward-compatible versions for older environments using the Grunt task runner. The current stable version is v8.0.0, which is specifically designed for compatibility with Babel 7.x. While Grunt itself has a slower release cadence compared to modern build tools, `grunt-babel` follows Babel's major version releases closely, necessitating updates to maintain compatibility. Its primary differentiator is its deep integration into the Grunt ecosystem, providing a familiar configuration experience for projects already utilizing Grunt for their build processes. It leverages Babel's extensive plugin and preset system, enabling a wide range of transformations, from JSX and TypeScript syntax stripping to polyfilling modern JavaScript features, making it suitable for projects that prefer a Grunt-centric workflow over newer alternatives like Webpack or Rollup.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/babel/grunt-babel","tags":["javascript","gruntplugin","babel","transpiler","es2015","rewriting","transformation","syntax","codegen"],"install":[{"cmd":"npm install grunt-babel","lang":"bash","label":"npm"},{"cmd":"yarn add grunt-babel","lang":"bash","label":"yarn"},{"cmd":"pnpm add grunt-babel","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core task runner dependency for any Grunt plugin.","package":"grunt","optional":false},{"reason":"The core Babel library responsible for transpilation; grunt-babel orchestrates its usage.","package":"@babel/core","optional":false},{"reason":"A common Babel preset to automatically determine necessary Babel plugins and polyfills based on target environments.","package":"@babel/preset-env","optional":true},{"reason":"A common utility for loading Grunt tasks from package.json, simplifying Gruntfile setup.","package":"load-grunt-tasks","optional":true}],"imports":[{"note":"grunt-babel is a Grunt task, not a library for direct import. Its functionality is configured via `grunt.initConfig`.","wrong":"import { babel } from 'grunt-babel';","symbol":"babel","correct":"grunt.initConfig({\n  babel: { /* ... */ }\n});"},{"note":"Configuration options are passed directly within the Grunt task definition object, not imported.","wrong":"const babelOptions = require('grunt-babel').options;","symbol":"options","correct":"grunt.initConfig({\n  babel: {\n    options: { sourceMap: true, presets: ['@babel/preset-env'] },\n    // ...\n  }\n});"},{"note":"This registers a Grunt task named 'default' that runs the 'babel' task. The `babel` task itself is implicitly registered by the plugin.","wrong":"grunt.registerTask('babel', ['default']);","symbol":"default task registration","correct":"grunt.registerTask('default', ['babel']);"}],"quickstart":{"code":"require('load-grunt-tasks')(grunt); // npm install --save-dev load-grunt-tasks\n\ngrunt.initConfig({\n  babel: {\n    options: {\n      sourceMap: true,\n      presets: ['@babel/preset-env'] // Ensure @babel/preset-env is installed\n    },\n    dist: {\n      files: {\n        'dist/app.js': 'src/app.js'\n      }\n    }\n  }\n});\n\ngrunt.registerTask('default', ['babel']);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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`).","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"Node.js v4 support was dropped in grunt-babel v8. Projects using older Node.js versions must remain on grunt-babel v7.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Manually install `@babel/core` (for v8+) or `babel-core` (for v7) in your project: `npm install --save-dev @babel/core`.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Verify your Babel configuration (presets, plugins) and report core transpilation issues on the official Babel GitHub repository.","message":"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.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install --save-dev @babel/core` or `yarn add --dev @babel/core`.","cause":"The `@babel/core` peer dependency is not installed.","error":"Error: Cannot find module '@babel/core'"},{"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.","cause":"Babel requires at least one preset or plugin to perform transformations. The options are empty or misconfigured.","error":"Error: You have not specified any presets or plugins for babel."},{"fix":"Ensure `@babel/preset-env` is configured to transform modules, e.g., `presets: [['@babel/preset-env', { modules: 'commonjs' }]]`.","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.","error":"SyntaxError: 'import' and 'export' may only appear at the top level (when running outputted JS)"}],"ecosystem":"npm"}