{"id":19296,"library":"babel-preset-gatsby-package","title":"babel-preset-gatsby-package","description":"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.","status":"active","version":"3.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript"],"install":[{"cmd":"npm install babel-preset-gatsby-package","lang":"bash","label":"npm"},{"cmd":"yarn add babel-preset-gatsby-package","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-preset-gatsby-package","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency — the preset requires @babel/core to function.","package":"@babel/core","optional":false}],"imports":[{"note":"The preset name is 'babel-preset-gatsby-package', not '@babel/preset-gatsby-package'. This is a scoping mistake commonly made.","wrong":"{\n  \"presets\": [\"@babel/preset-gatsby-package\"]\n}","symbol":"default (preset config)","correct":"{\n  \"presets\": [\"babel-preset-gatsby-package\"]\n}"},{"note":"The `browser` option must be passed inside the preset configuration array, not at the top-level .babelrc.","wrong":"{\n  \"presets\": [\"babel-preset-gatsby-package\"],\n  \"browser\": true\n}","symbol":"browser option","correct":"{\n  \"presets\": [\n    [\"babel-preset-gatsby-package\", { \"browser\": true }]\n  ]\n}"},{"note":"Set Node version via `nodeVersion` in this preset's options, not by setting `targets` directly, as `targets` would be overridden by the preset.","wrong":"{\n  \"presets\": [\"babel-preset-gatsby-package\"],\n  \"targets\": { \"node\": \"14\" }\n}","symbol":"nodeVersion option","correct":"{\n  \"presets\": [\n    [\"babel-preset-gatsby-package\", { \"nodeVersion\": \"14\" }]\n  ]\n}"}],"quickstart":{"code":"// .babelrc\n{\n  \"presets\": [\n    [\"babel-preset-gatsby-package\", {\n      \"browser\": false,\n      \"debug\": false,\n      \"nodeVersion\": \"18.0\"\n    }]\n  ]\n}","lang":"json","description":"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."},"warnings":[{"fix":"Remove this preset and install babel-preset-gatsby for site usage.","message":"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.","severity":"gotcha","affected_versions":">=0"},{"fix":"Explicitly set `nodeVersion` to match your target Node version to avoid unexpected transpilation.","message":"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.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Consider migrating to a newer Babel preset or fork if active updates are needed.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Explicitly set `nodeVersion` to your target Node version to reduce unnecessary transforms.","message":"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.","severity":"gotcha","affected_versions":">=0"},{"fix":"Remove any duplicate class-properties or optional-chaining plugins from your Babel config.","message":"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.","severity":"gotcha","affected_versions":">=0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install --dev @babel/core @babel/preset-env @babel/preset-react @babel/preset-flow`","cause":"Missing peer dependency @babel/core or its presets/plugins.","error":"Cannot find module '@babel/preset-env'"},{"fix":"Run `npm install --dev babel-preset-gatsby-package`","cause":"The preset is not installed.","error":"Error: [BABEL] unknown preset \"babel-preset-gatsby-package\""},{"fix":"Update @babel/core to ^7.11.6 or later.","cause":"Using an incompatible version of @babel/core (older than 7.x).","error":"Plugin/Preset files are not allowed to export objects, only functions."},{"fix":"Update to babel-preset-gatsby-package@3 or later.","cause":"Using an older version of the preset before the 'browser' option was added (pre-v3).","error":"The 'browser' option is not recognized."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}