#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',
  },
});

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

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

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.

#Extending configurations

See Extending Configurations for details on how to extend configurations from other files or packages.

#TypeScript configuration file

When using rspack.config.ts, you can choose from one of the following approaches:

#Default behavior

Starting from v1.5.0, Rspack CLI has built-in support for TypeScript configuration, using SWC by default to transform TypeScript code into CommonJS format JavaScript code.

If you're using a Rspack CLI earlier than v1.5.0, it's recommended to upgrade to the latest version. You no longer need to load configuration files through ts-node or esbuild-register, and these dependencies can be removed.

#Native support

If your JavaScript runtime already natively supports TypeScript, you can use the built-in TS transformation to load the configuration file, ensuring that module resolution behavior is consistent with native behavior.

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.18+ and v24.3+ which support native TypeScript by default, you can run the following command to load the TS config:

{
  "scripts": {
    "build": "rspack build --configLoader=native"
  }
}

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

yarn add esbuild esbuild-register -D

pnpm add esbuild esbuild-register -D

bun add esbuild esbuild-register -D

deno add npm:esbuild npm: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

yarn add ts-node -D

pnpm add ts-node -D

bun add ts-node -D

deno add npm: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',
  },
});

// @ts-check
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 Rspack's extends option or webpack-merge package to merge multiple Rspack configurations.

#extends option

When using @rspack/cli, Rspack provides the extends option, allowing you to extend configurations from other files or packages.

export default {
  extends: './base.rspack.config.mjs',
  output: {
    filename: '[name].bundle.js',
  },
};

This option is only supported in @rspack/cli, see extends for more usage.

#webpack-merge

webpack-merge is a community library for merging multiple webpack configurations, and it can also be used to merge Rspack configurations.

First install webpack-merge:

npm add webpack-merge -D

yarn add webpack-merge -D

pnpm add webpack-merge -D

bun add webpack-merge -D

deno add npm:webpack-merge -D

Then you can use its merge function to merge configurations:

import { merge } from 'webpack-merge';

const isDev = process.env.NODE_ENV === 'development';
const base = {};
const dev = {
  plugins: [new SomeDevPlugin()],
};

export default isDev ? merge(base, dev) : base;

See webpack-merge documentation for more details.