Registry / devops / babel-preset-gatsby-package

babel-preset-gatsby-package

library3.16.0jsnpmunverified

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.

devops web-framework

npm install babel-preset-gatsby-package

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BABEL-PRESET-GATSB

babel-preset-gatsby-package

devopsjavascriptv3.16.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (preset config)

✓ { "presets": ["babel-preset-gatsby-package"] }

✗ { "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

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

✗ { "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

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

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

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

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" }] ] }

Debug

Known issues

gotchaThis 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.

affects: >=0

breakingThe `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.

affects: <3.0.0

deprecatedThis 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.

affects: >=3.0.0

gotchaIf 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.

affects: >=0

gotchaThe 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.

affects: >=0

Errors

Common errors & fixes

Cannot find module '@babel/preset-env'

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: [BABEL] unknown preset "babel-preset-gatsby-package"

The preset is not installed.

fix

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

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

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

fix

Update @babel/core to ^7.11.6 or later.

The 'browser' option is not recognized.

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.

Upgrade

Version history

3.16.0latest on npm

Audit

Dependencies

@babel/corerequiredPeer dependency — the preset requires @babel/core to function.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/babel-preset-gatsby-package ↗

homepagehttps://www.gatsbyjs.com ↗