babel-preset-gatsby-package

3.16.0 verified Sat Apr 25 auth: no javascript

Babel preset used internally by Gatsby for developing Gatsby packages. It bundles @babel/preset-env, @babel/preset-react, @babel/preset-flow, and several plugins (class properties, optional chaining, transform-runtime). Designed for package authors, not Gatsby site users. Current stable version is 3.16.0, part of Gatsby v5 ecosystem. Released on npm alongside Gatsby releases (~monthly). Supports Node 18+. Key differentiator: automatically configures browser vs Node targets via the `browser` option, tailored for Gatsby package development rather than general React apps.

Common errors

error Cannot find module '@babel/preset-env' ↓

cause Missing peer dependency @babel/core or its presets/plugins.

fix

Run npm install --dev @babel/core @babel/preset-env @babel/preset-react @babel/preset-flow

error Error: [BABEL] unknown preset "babel-preset-gatsby-package" ↓

cause The preset is not installed.

fix

Run npm install --dev babel-preset-gatsby-package

error Plugin/Preset files are not allowed to export objects, only functions. ↓

cause Using an incompatible version of @babel/core (older than 7.x).

fix

Update @babel/core to ^7.11.6 or later.

error The 'browser' option is not recognized. ↓

cause Using an older version of the preset before the 'browser' option was added (pre-v3).

fix

Update to babel-preset-gatsby-package@3 or later.

Warnings

gotcha This preset is for developing Gatsby packages, NOT for Gatsby sites. Do NOT use it in a Gatsby site's .babelrc; use babel-preset-gatsby instead. ↓

fix Remove this preset and install babel-preset-gatsby for site usage.

breaking The `nodeVersion` option default changed from '10.13' in older versions to the Node engine requirement. The current default is '10.13' as per documentation, but the package itself requires Node >=18.0.0. This mismatch can cause confusion. ↓

fix Explicitly set `nodeVersion` to match your target Node version to avoid unexpected transpilation.

deprecated This package is part of the Gatsby v5 ecosystem, which is in maintenance mode. Active development has moved to Gatsby v6 (Gatsby 6) if applicable. Check the Gatsby monorepo for the latest. ↓

fix Consider migrating to a newer Babel preset or fork if active updates are needed.

gotcha If you set `browser: false`, the preset assumes Node.js environment and includes `@babel/preset-env` with targets `{node: '10.13'}` by default. This may include transforms not needed for modern Node versions. ↓

fix Explicitly set `nodeVersion` to your target Node version to reduce unnecessary transforms.

gotcha The preset includes `@babel/plugin-proposal-class-properties` and `@babel/plugin-proposal-optional-chaining`, which may conflict with similar plugins already configured. Duplicate plugins can cause errors. ↓

fix Remove any duplicate class-properties or optional-chaining plugins from your Babel config.

Install

npm install babel-preset-gatsby-package

yarn add babel-preset-gatsby-package

pnpm add babel-preset-gatsby-package

Imports

default (preset config)
wrong
```
{
  "presets": ["@babel/preset-gatsby-package"]
}
```
correct
```
{
  "presets": ["babel-preset-gatsby-package"]
}
```
The preset name is 'babel-preset-gatsby-package', not '@babel/preset-gatsby-package'. This is a scoping mistake commonly made.

browser option

wrong

{
  "presets": ["babel-preset-gatsby-package"],
  "browser": true
}

correct

{
  "presets": [
    ["babel-preset-gatsby-package", { "browser": true }]
  ]
}

The `browser` option must be passed inside the preset configuration array, not at the top-level .babelrc.

nodeVersion option

wrong

{
  "presets": ["babel-preset-gatsby-package"],
  "targets": { "node": "14" }
}

correct

{
  "presets": [
    ["babel-preset-gatsby-package", { "nodeVersion": "14" }]
  ]
}

Set Node version via `nodeVersion` in this preset's options, not by setting `targets` directly, as `targets` would be overridden by the preset.

Quickstart

Basic configuration for a Gatsby package targeting Node.js 18+. The 'browser' option set to false (default) targets Node; set to true for browser targets.

// .babelrc
{
  "presets": [
    ["babel-preset-gatsby-package", {
      "browser": false,
      "debug": false,
      "nodeVersion": "18.0"
    }]
  ]
}