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:

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

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

Configuration file formats#

Rspack supports these configuration file 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.

Note that Rspack will first search JS configuration file and then TS configuration file.

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

TypeScript configuration file#

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

Native support#

If your JavaScript runtime already natively supports TypeScript, you can use the built-in TS transformation to load the configuration file without needing to install additional dependencies.

For example, Node.js already natively supports TypeScript, you can use the following command to use the Node.js native loader to load the configuration file:

• For Node.js v22.7.0 to v23.5.0, you need to enable the --experimental-transform-types flag:

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

• For Node.js v23.6.0+, the --experimental-transform-types flag is no longer required:

{
  "scripts": {
    "build": "rspack build"
  }
}

See Node.js - Running TypeScript Natively for more details.

Using esbuild#

For lower Node.js versions, you can use esbuild-register to load the configuration file.

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

npm add esbuild esbuild-register -D

Using ts-node#

You can also use ts-node to load the configuration file.

1. Install ts-node:

npm add ts-node -D

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

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

Type checking#

Use the defineConfig helper to enable auto-completion. For JavaScript configuration files, you can use the // @ts-check comment to enable type checking.

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

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

Alternatively, you can use JSDoc for type checking.

// @ts-check
/** @type {import('@rspack/cli').Configuration} */
const config = {
  entry: {
    main: './src/index.js',
  },
};
export default config;

Specify the configuration file#

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"
  }
}

Abbreviate the --config option to -c:

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

Exporting a configuration function#

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

export default 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:

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

Merge configurations#

Use the merge function exported by webpack-merge to merge multiple configurations.

import { merge } from 'webpack-merge';

const base = {};

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

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

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