#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.ts: TypeScript format, see TypeScript configuration file for more details.
• rspack.config.js: defaults to CommonJS format, or ES modules format if the type of the package.json is "module".
• rspack.config.mts: Forced to ES modules + TypeScript format.
• rspack.config.mjs: Forced to ES modules format.
• rspack.config.cts: Forced to CommonJS + TypeScript format.
• rspack.config.cjs: Forced to CommonJS format.

Rspack resolves configuration files in the following order by default:

rspack.config.ts > rspack.config.js > rspack.config.mts > rspack.config.mjs > rspack.config.cts > rspack.config.cjs

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.

By default, Rspack CLI uses --configLoader=auto:

• JavaScript config files are loaded with the native runtime loader.
• When the runtime supports native TypeScript, Rspack CLI tries the native loader first and falls back to Jiti if loading fails.
• On runtimes without native TypeScript support, Rspack CLI loads TypeScript config files with Jiti directly.

If you're using a Rspack CLI earlier than v1.5.0, it's recommended to upgrade to the latest version.

#Native support

If your JavaScript runtime already natively supports TypeScript, you can force the native loader 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.

#Jiti loader

You can also force Rspack CLI to load TypeScript config files through Jiti:

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

#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.