Babel Preset Razzle

4.2.18 verified Sat Apr 25 auth: no javascript

Babel preset used by Razzle, a zero-configuration universal JavaScript framework. Current stable version is 4.2.18. It provides a pre-configured set of plugins for React, including JSX, object rest spread, and dynamic import. Designed for server-side rendering (SSR) with automatic environment detection based on BABEL_ENV or NODE_ENV. It ships as a CommonJS module and is not meant to be used outside of Razzle unless you manually configure Babel. Released as part of the Razzle monorepo with updates tied to Razzle releases.

Common errors

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

cause The package is not installed or not in node_modules.

fix

Run npm install --save-dev babel-preset-razzle.

error Unknown option 'corejs' in preset 'razzle' ↓

cause You may be using an older version of babel-preset-razzle that does not support `corejs` option.

fix

Upgrade to babel-preset-razzle@4 or later, or remove the corejs option and use the default core-js@2 behavior.

error Support for the experimental syntax 'classProperties' isn't currently enabled ↓

cause The preset may not include the necessary plugin for class properties if you are using an older version.

fix

Ensure you are using babel-preset-razzle@4 or later, or add @babel/plugin-proposal-class-properties manually.

Warnings

gotcha The preset automatically swaps between server and client presets based on BABEL_ENV or NODE_ENV. Setting both NODE_ENV=production and BABEL_ENV=server will use server preset with @babel/preset-env targeting node, while BABEL_ENV=client (or unset) will target browsers. Failing to set BABEL_ENV correctly leads to wrong target environment and broken SSR. ↓

fix Set BABEL_ENV appropriately for your build scripts: BABEL_ENV=server for server bundle, BABEL_ENV=client for client bundle.

deprecated The `useBuiltIns` option defaults to 'usage' with core-js@2. As of Razzle 4, core-js@3 is recommended. Using the default polyfill behavior may cause missing polyfills or duplicate imports. ↓

fix Add options to .babelrc: { presets: [['razzle', { corejs: 3 }]] } and install core-js@3.

breaking In v4, the preset was refactored from a single preset to a function that returns different configurations. This may break custom overrides that relied on the Babel plugin list being static. ↓

fix Update any custom Babel config that extends or overrides razzle preset to use the function form and inspect the returned config objects.

gotcha The preset does not include typescript or flow. If you need TypeScript, you must add @babel/preset-typescript separately or use razzle-plugin-typescript. ↓

fix Install and configure @babel/preset-typescript or use the official razzle-plugin-typescript plugin.

deprecated Support for Node.js versions below 10.13.0 was dropped in Razzle 4. The preset may emit code with syntax that does not work on older Node.js versions. ↓

fix Upgrade Node.js to >=10.13.0 or configure @babel/preset-env targets explicitly.

Install

npm install babel-preset-razzle

yarn add babel-preset-razzle

pnpm add babel-preset-razzle

Imports

default

wrong

import preset from 'babel-preset-razzle';

correct

module.exports = require('babel-preset-razzle');

This preset is a CommonJS module; ESM import is not supported.

babel-preset-razzle
wrong
```
{
  "presets": ["babel-preset-razzle"]
}
```
correct
```
{
  "presets": ["razzle"]
}
```
In .babelrc, use the short name 'razzle' not the full package name.

babel.config.js

wrong

module.exports = {
  presets: ['razzle']
};

correct

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['razzle']
  };
};

In babel.config.js, exporting an object may cause caching issues; use a function with api.cache() instead.

Quickstart

Basic setup of babel-preset-razzle in .babelrc with custom targets and options.

// Install Babel and this preset
// npm install --save-dev @babel/core babel-preset-razzle

// .babelrc
{
  "presets": [
    ["razzle", {
      "targets": {
        "browsers": ["last 2 versions", "ie >= 11"],
        "node": "current"
      },
      "modules": false,
      "useBuiltIns": "usage",
      "corejs": 3
    }]
  ]
}

// Example usage with Babel CLI
// npx babel src --out-dir lib

// This configures the preset for SSR (node) and client (browsers) targets.
// The preset automatically detects the environment: 'server' for NODE_ENV=production with BABEL_ENV=server, else 'client'.
// Use BABEL_ENV to toggle between server and client builds.
// Note: The preset uses @babel/preset-env with 'useBuiltIns: usage' and assumes Object.assign is polyfilled.