babel-preset-gatsby

3.16.0 verified Sat Apr 25 auth: no javascript

Official Babel preset for Gatsby projects, providing a curated set of plugins and presets to enable modern JavaScript and React support while targeting older browsers and Node.js. Current stable version is 3.16.0, released as part of Gatsby 5.x ecosystem. Release cadence follows Gatsby major releases. Key features include automatic polyfilling via core-js, optimized production builds with plugin-transform-react-remove-prop-types, and support for both classic and automatic JSX runtime. Differs from generic Babel presets by being tuned specifically for Gatsby's build pipeline, including optimizations like hook destructuring and dynamic import syntax.

Common errors

error Error: Cannot find module 'babel-preset-gatsby' ↓

cause babel-preset-gatsby not installed or not in node_modules.

fix

Run 'npm install babel-preset-gatsby' or ensure it's in dependencies.

error ReferenceError: regeneratorRuntime is not defined ↓

cause Missing @babel/runtime or core-js polyfill for async/await.

fix

Add '@babel/plugin-transform-runtime' to Babel plugins, or ensure core-js is installed.

error TypeError: Cannot read properties of undefined (reading 'some') ↓

cause Incorrect Babel config syntax (e.g., passing options as separate argument instead of array).

fix

Use array syntax: ['babel-preset-gatsby', { options }].

Warnings

breaking babel-preset-gatsby v3 requires Gatsby 5.x and Node >=18. Do not use with Gatsby 4.x or Node 16. ↓

fix Upgrade to Gatsby 5.x and Node >=18.

deprecated As of Gatsby 5, the preset is included automatically. Explicit installation is only needed if customizing Babel. ↓

fix Remove explicit dependency unless you need custom Babel config.

gotcha When using core-js@3, ensure it is installed as a peer dependency. Missing core-js can cause 'Cannot find module' errors. ↓

fix Run 'npm install core-js@3' in your project.

gotcha The 'targets' option overrides Gatsby's default browser targets. Setting too narrow targets may break polyfilling for older browsers. ↓

fix Only override targets if you fully understand the implications for browser support.

Install

npm install babel-preset-gatsby

yarn add babel-preset-gatsby

pnpm add babel-preset-gatsby

Imports

default

wrong

import babelPresetGatsby from 'babel-preset-gatsby'

correct

module.exports = { presets: ['babel-preset-gatsby'] }

Not a JavaScript import; used in .babelrc or babel.config.js as a string reference.

babel-preset-gatsby

wrong

{ presets: [require('babel-preset-gatsby')] }

correct

{ presets: ['babel-preset-gatsby'] }

In .babelrc, use the string name, not require().

options (targets, reactRuntime, reactImportSource)

wrong

{ presets: ['babel-preset-gatsby', { targets: ... }] }

correct

{ presets: [['babel-preset-gatsby', { targets: { browsers: ['last 2 versions'] } }]] }

Options must be passed as an array with the preset string as first element.

Quickstart

Shows how to use babel-preset-gatsby in a .babelrc file, with optional configuration.

// .babelrc
{
  "presets": ["babel-preset-gatsby"]
}

// Or with options:
// {
//   "presets": [
//     [
//       "babel-preset-gatsby",
//       {
//         "targets": {
//           "browsers": ["last 2 versions", "not ie 11"]
//         },
//         "reactRuntime": "automatic"
//       }
//     ]
//   ]
// }