Getting Started

Quick Start

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

If you've previously installed create-razzle-app globally via npm install -g create-razzle-app, we recommend you uninstall the package using npm uninstall -g create-razzle-app or yarn global remove create-razzle-app to ensure that npx always uses the latest version.

(npx comes with npm 5.2+ and higher, see instructions for older npm versions)

Then open http://localhost:3000/ to see your app. Your console should look like this:

That's it. You don't need to worry about setting up multiple webpack configs or other build tools. Just start editing src/App.js and go!

Razzle has many examples, we might have one that fits your needs

See: The examples

Commands

Below is a list of commands you will probably find useful.

npm start

Runs the project in development mode. You can view your application at http://localhost:3000

The page will reload if you make edits.

npm run build

Builds the app for production to the build folder.

The build is minified and the filenames include the hashes. Your app is ready to be deployed!

By default this uses NODE_ENV=production and asks if you want to run it.

If you don't want the confirmation add --noninteractive to your build command.

If you want to use a different env file e.g. .env.something-staging file you can add --node-env=something-staging

npm run start:prod

Runs the compiled app in production.

You can again view your application at http://localhost:3000

npm test

Runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit.

Exports a static version of the application in production mode. Must add the export command to package.json's scripts along with a static_export.js file in the src directory. See Static Site Generation for more details.

rs

If your application is running, and you need to manually restart your server, you do not need to completely kill and rebundle your application. Instead you can just type rs and press enter in terminal.

Dependencies

To make sure Razzle is installed properly make sure Razzle devDependencies are installed, run:

yarn add --dev \
  razzle \
  razzle-dev-utils \
  babel-preset-razzle

... and Razzle peerDependencies are installed, run:

yarn add --dev \
  webpack-dev-server@3.11.0 \
  mini-css-extract-plugin@0.9.0 \
  postcss@8.2.4

Choose your webpack version

yarn add --dev webpack@5.24.0 html-webpack-plugin@5.2.0
# or
yarn add --dev webpack@4.46.0 html-webpack-plugin@4.5.2

Also if there are issues, try adding specific package versions to resolutions in package.json.

Common issues

If you have issues with css this might be related to postcss being resolved wrong.

To fix this add:

{
  "postcss": "8.2.4"
}

To resolutions in your package.json. For npm see here.

If you get an error like this:

node_modules/react-images-upload/index.css:1
.fileUploader {
^

SyntaxError: Unexpected token '.'
    at wrapSafe (internal/modules/cjs/loader.js:1072:16)

It means node tries to use index.css as a node module.

To fix this make sure the module with the css is not externalized.

// razzle.config.js
'use strict';
module.exports = {
  modifyWebpackOptions({
    options: {
      webpackOptions, // the modified options that was used to configure webpack/ webpack loaders and plugins
    }
  }) {
      webpackOptions.notNodeExternalResMatch = (request, context) => {
         return /react-images-upload/.test(request)
      };
    return webpackOptions;
  },
};

Dev server not starting and no errors show up

Make razzle more verbose:

// razzle.config.js
'use strict';
module.exports = {
  options: {
    verbose: true
  }
};

Debugging with Inspector

npm start -- --inspect=[host:port] or yarn start --inspect=[host:port] This will start the node server and enable the inspector agent. The =[host:port] is optional and defaults to =127.0.0.1:9229. For more information, see this.
npm start -- --inspect-brk=[host:port] or yarn start --inspect-brk=[host:port] This is the same as --inspect, but will also break before user code starts. (to give a debugger time to attach before early code runs) For more information, see this.
npm test -- --inspect=[host:port] or yarn test --inspect=[host:port] This will start the tests server and enable the inspector agent. The =[host:port] is optional and defaults to =127.0.0.1:9229. For more information, see this.
npm test -- --inspect-brk=[host:port] or yarn test --inspect-brk=[host:port] This is the same as --inspect, but will also break before user code starts. (to give a debugger time to attach before early code runs) For more information, see this.