Razzle Documentation

Razzle is a tool designed to abstract the complex configuration required for both Single Page Applications (SPA) and Server-Side Rendering (SSR) applications. It provides a developer experience similar to create-react-app but allows you to maintain control over architectural decisions like routing and data fetching.

Key features include:

• Universal Hot Module Replacement (HMR): Both client and server update automatically on edits.
• ES6 Support: Built-in support via babel-preset-razzle.
• CSS Support: Uses the same CSS setup as create-react-app.
• Framework Agnostic: Works with React, Preact, Reason-React, Angular, and Vue.
• Customization: Provides escape hatches via .babelrc and razzle.config.js.
• Testing: Includes a Jest test runner setup via the razzle test command.
• SPA Mode: Capability to build client-side only applications.

In development mode (razzle start), Razzle operates using two parallel webpack instances that watch the same filesystem to ensure synchronized hot reloading.

Key architectural details:

• Dual Bundling: Razzle bundles both client and server code simultaneously using different webpack instances.
• Server: Runs on the port specified in src/index.js (default: 3000).
• Client: Served via webpack-dev-server on a separate port (default: 3001).
• Public Path: The client bundle uses an absolute URL for its publicPath (e.g., localhost:3001) rather than a relative path like /. This allows the server's HTML template to point directly to the client JS (e.g., localhost:3001/static/js/client.js).
• Consistency: Because both instances use the same loaders and Babel transformations, you avoid common issues like React checksum mismatches during hydration.

You can define environment variables for the duration of a single shell session. The syntax depends on your operating system.

### Windows (cmd.exe)
```cmd
set RAZZLE_SECRET_CODE=abcdef&&npm start

Linux, macOS (Bash)

RAZZLE_SECRET_CODE=abcdef npm start

To add Vue support to your Razzle project, install the razzle-plugin-vue package using yarn.

yarn add razzle-plugin-vue

If you need to transpile external modules (e.g., those containing arrow functions), you must ensure they are not externalized and are added to the babelRule.include array within your razzle.config.js using the modifyWebpackOptions hook.

// razzle.config.js
'use strict';

module.exports = {
  modifyWebpackOptions({
    env: {
      target, // the target 'node' or 'web'
      dev, // is this a development build? true or false
    },
    options: {
      webpackOptions, // the default options that will be used to configure webpack/ webpack loaders and plugins
    }
  }) {
    webpackOptions.notNodeExternalResMatch = (request, context) => {
       return /themodule|anothermodule/.test(request)
    };
    webpackOptions.babelRule.include = webpackOptions.babelRule.include.concat([
      /themodule/,
      /anothermodule/
    ]);
    return webpackOptions;
  }
};

You can scaffold a new Razzle application quickly using npx. It is recommended to uninstall any global installations of create-razzle-app first to ensure you always use the latest version via npx.

npx create-razzle-app my-app
cd my-app
npm start

You can expand existing machine environment variables or variables defined within the same .env file using the $ syntax.

# Expand machine variables
RAZZLE_VERSION=$npm_package_version
# or
RAZZLE_VERSION=${npm_package_version}

# Expand local .env variables
DOMAIN=www.example.com
RAZZLE_FOO=$DOMAIN/foo
RAZZLE_BAR=$DOMAIN/bar

To enable TypeScript support using the plugin's default settings, add 'typescript' to the plugins array in your razzle.config.js file.

// razzle.config.js

module.exports = {
  plugins: ['typescript'],
};

To use the Razzle Babel preset in a project that is not built with Razzle, follow these steps:

1. Install Babel in your project.
2. Create a .babelrc file in your project's root directory.
3. Add "presets": ["razzle"] to the .babelrc file.

Note: This preset uses the useBuiltIns option with transform-object-rest-spread, which assumes that Object.assign is available or polyfilled in your environment.

Add StartServerPlugin to the plugins array in your server-side Webpack configuration (e.g., webpack.config.server.babel.js). This plugin automatically starts your server once the Webpack build completes and handles Hot Module Replacement (HMR).

Note: It is recommended to only use this plugin in DEVELOPMENT mode.

import StartServerPlugin from "start-server-webpack-plugin";

export default {
  // ...
  plugins: [
    // ...
    new StartServerPlugin({
      verbose: true,
      debug: false,
      entryName: 'server',
      nodeArgs: ['--inspect-brk'],
      scriptArgs: ['scriptArgument1', 'scriptArgument2'],
      restartable: true,
      once: false,
    }),
    // ...
  ],
  // ...
}

Create a .env file in your project root to define permanent variables. Razzle supports multiple .env files with specific loading priorities based on the command being run.

File Priority (Highest to Lowest)

• npm start: .env.development.local > .env.development > .env.local > .env
• npm run build: .env.production.local > .env.production > .env.local > .env
• npm test: .env.test.local > .env.test > .env (Note: .env.local is not loaded during tests)

Supported Files

• .env: Default.
• .env.local: Local overrides (loaded for all environments except test).
• .env.development, .env.test, .env.production: Environment-specific settings.
• .env.[environment].local: Local overrides for specific environments.