Configure Rspack#

Rspack provides configurations similar to webpack. This chapter will show you how to use the Rspack configuration.

Configuration file#

When you run the Rspack CLI, Rspack automatically reads the rspack.config.* file in the current working directory.

A basic Rspack configuration file looks like this:

export default {
  entry: {
    main: './src/index.js',
  },
};

Configuration file formats#

Rspack supports four types of configuration files, .js, .ts, .cjs and .mjs formats.

• rspack.config.js: defaults to CommonJS format, or ES modules format if the type of the package.json is module.
• rspack.config.ts: TypeScript format, see TypeScript Configuration File for more details.
• rspack.config.cjs: Forced to CommonJS format.
• rspack.config.mjs: Forced to ES modules format.

See ES modules and CommonJS for the difference between CommonJS and ES modules.

TypeScript configuration file#

When using rspack.config.ts, you need to install additional dependencies to resolve TypeScript files. You can choose one of the following:

Using esbuild#

Install esbuild and esbuild-register, no additional configuration is needed.

npm add esbuild esbuild-register -D

Using ts-node#

Install ts-node:

npm add ts-node -D

Then configure ts-node to use CommonJS modules in tsconfig.json:

{
  "ts-node": {
    "compilerOptions": {
      "module": "CommonJS"
    }
  }
}

Type checking#

rspack.config.js is a JavaScript file, you can use JSDoc to enable the IDE's Intellisense and TypeScript type checking.

// @ts-check

/** @type {import('@rspack/cli').Configuration} */
const config = {
  entry: {
    main: './src/index.js',
  },
};
module.exports = config;

Alternatively, you can use the defineConfig helper, which provides auto-completion of the configuration:

// @ts-check

const { defineConfig } = require('@rspack/cli');

const config = defineConfig({
  entry: {
    main: './src/index.js',
  },
});
module.exports = config;

Alternatively, you can use TypeScript as configuration file. The default TypeScript configuration file name is rspack.config.ts.

import { Configuration } from '@rspack/cli';

const config: Configuration = {
  entry: {
    main: './src/index.js',
  },
};

export = config;

You need to install ts-node as devDependencies so that Rspack can resolve the ts extension.

{
  "devDependencies": {
    "ts-node": "^10.9.2"
  }
}

If the version of Node.js you are using supports the --experimental-transform-types flag, you can use the built-in TS transformation of Node.js without needing to install ts-node.

{
  "build": "NODE_OPTIONS=--experimental-transform-types rspack build"
}

Note that Rspack will first search JavaScript and then TypeScript if the JS file does not exist.

Specify the configuration file#

You can specify the name of the configuration file using the --config option.

For example, if you need to use the rspack.prod.config.js file when running build, you can add the following scripts to package.json:

{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build --config rspack.prod.config.js"
  }
}

You can also abbreviate the --config option to -c:

$ rspack build -c rspack.prod.config.js

Exporting a configuration function#

Rspack supports exporting a function in rspack.config.js, you can dynamically compute the configuration in the function and return it to Rspack.

module.exports = function (env, argv) {
  return {
    devtool: env.production ? 'source-map' : 'eval',
  };
};

As you can see from the example above, the function takes two input parameters:

• The first argument is env, which corresponds to the value of the --env option when running the CLI command.
• The second argument is argv, which contains all the options passed to the CLI.

Determine the current environment#

In addition to passing the env parameter, it is more common to use process.env.NODE_ENV to determine the current environment:

module.exports = function (env, argv) {
  const isProduction = process.env.NODE_ENV === 'production';
  return {
    devtool: isProduction ? 'source-map' : 'eval',
  };
};

Merge configurations#

You can use the merge function exported by webpack-merge to merge multiple configurations.

const { merge } = require('webpack-merge');

const base = {};

const dev = {
  plugins: [new DevelopmentSpecifiedPlugin()],
};

module.exports =
  process.env.NODE_ENV === 'development' ? merge(base, dev) : base;

For more information of merge, please refer to webpack-merge documentation.