#Optimization

Rspack will select appropriate optimization configuration based on the mode. You can also customize the configuration via optimization.

#optimization.avoidEntryIife

• Type: boolean
• Default:false

Use optimization.avoidEntryIife to avoid wrapping the entry module in an IIFE when it is required (search for "This entry needs to be wrapped in an IIFE because" in rspack_plugin_javascript). This approach helps optimize performance for JavaScript engines and helps tree shaking when building ESM libraries.

Currently, optimization.avoidEntryIife can only optimize a single entry module along with other modules.

export default {
  optimization: {
    avoidEntryIife: true,
  },
};

#optimization.chunkIds

• Type: false | 'natural' | 'named' | 'deterministic' | 'compact-hashed' | 'size' | 'total-size'
• Default:development mode is'named', production mode is'deterministic'

Tells Rspack which algorithm to use when generating chunk ids.

The following values are supported:

export default {
  optimization: {
    chunkIds: 'deterministic',
  },
};

Custom JavaScript plugins cannot currently assign chunk IDs. When you set chunkIds to false, add a chunk ID plugin from rspack.ids to plugins:

import { rspack } from '@rspack/core';

export default {
  optimization: {
    chunkIds: false,
  },
  plugins: [new rspack.ids.CompactHashedChunkIdsPlugin()],
};

The compact-hashed option uses the shortest available prefix of a stable lowercase alphanumeric hash as the chunk id, balancing long-term caching, bundle size, and runtime performance.

export default {
  optimization: {
    chunkIds: 'compact-hashed',
  },
};

#optimization.concatenateModules

• Type: boolean
• Default:production mode istrue, development mode isfalse

Tells Rspack to find segments of the module graph which can be safely concatenated into a single module. Depends on optimization.providedExports and optimization.usedExports. By default optimization.concatenateModules is enabled in production mode and disabled elsewise.

export default {
  optimization: {
    concatenateModules: false,
  },
};

#optimization.emitOnErrors

• Type: boolean
• Default:production mode isfalse, development mode istrue

Use the optimization.emitOnErrors to emit assets whenever there are errors while compiling. This ensures that erroring assets are emitted. The errors are emitted into the generated code and will cause errors at runtime.

export default {
  optimization: {
    emitOnErrors: true,
  },
};

#optimization.inlineExports

• Type: boolean
• Default:production mode istrue, development mode isfalse

Performs cross-module inline optimization for:

1. Exported top-level constant values that can be statically evaluated:

   • null or undefined
   • boolean values (true or false)
   • number with length <= 6
   • string with length <= 6

2. Exported TypeScript enums that collected by builtin:swc-loader collectTypeScriptInfo.exportedEnum

This optimization helps reduce bundle size and can improve runtime performance.

A common use case is with constants.js files:

// constants.js
export const A = true;
export const B = 'hello';

// index.js
import { A, B } from './constants';
console.log(A ? 1 : 2);
console.log(B.length);

When inlineExports is enabled, constant values will be inlined at their usage sites:

// Bundled by Rspack: output.js
const __webpack_modules__ = {
  './index.js': () => {
    // Constants are inlined directly
    console.log(true ? 1 : 2);
    console.log('hello'.length);
    // If all exports from constants.js are inlined, the constants.js module
    // will be optimized away and won't appear in the final output
  },
};

For more details, refer to the inline const example.

#optimization.innerGraph

• Type: boolean
• Default:production mode istrue, development mode isfalse

optimization.innerGraph tells Rspack whether to perform a more detailed analysis of variable assignments. This helps Rspack to identify unused module exports, thereby reducing the size of the bundled output.

For example:

import { value } from 'lib';

const value2 = value;

function f1() {
  console.log(value);
}

function f2() {
  console.log(value2);
}

Here we assign the value to value2. Both value2 and value are accessed within the functions f2 and f1 respectively, but the functions are not called, hence value2 and value are not actually used, thus the import of value can be removed.

#optimization.mangleExports

• Type: boolean | 'deterministic' | 'size'
• Default:production mode istrue, development mode isfalse

optimization.mangleExports controls how export names are mangled.

The following values are supported:

For example, with the following source code:

export const veryLongExportName = 1;

When mangleExports is disabled, the export name is preserved:

__webpack_require__.d(__webpack_exports__, {
  veryLongExportName: () => veryLongExportName,
});

When mangleExports is set to 'size', the export name is shortened:

export default {
  optimization: {
    mangleExports: 'size',
  },
};

__webpack_require__.d(__webpack_exports__, {
  a: () => veryLongExportName,
});

#optimization.mergeDuplicateChunks

• Type: boolean
• Default:true

Whether to merge chunks which contain the same modules. Setting optimization.mergeDuplicateChunks to false will disable this optimization.

export default {
  optimization: {
    mergeDuplicateChunks: false,
  },
};

#optimization.minimize

• Type: boolean
• Default:production mode istrue, development mode isfalse

Whether to use the minimizer declared in optimization.minimizer to minimize the bundle.

export default {
  optimization: {
    minimize: true,
  },
};

#optimization.minimizer

• Type: ('...' | Plugin)[]
• Default:[new SwcJsMinimizerRspackPlugin(), new LightningCssMinimizerRspackPlugin()]

Customize the minimizer. By default, rspack.SwcJsMinimizerRspackPlugin and rspack.LightningCssMinimizerRspackPlugin are used.

When optimization.minimizer is specified, the default minimizers will be disabled.

import TerserPlugin from 'terser-webpack-plugin';

export default {
  optimization: {
    minimizer: [new TerserPlugin()],
  },
};

Use Rspack's built-in minimizer with custom options:

import { rspack } from '@rspack/core';

export default {
  optimization: {
    // when `optimization.minimizer` is specified, the default minimizers are disabled by default
    // but you can use '...', it represents the default minimizers
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        minimizerOptions: {
          format: {
            comments: false,
          },
        },
      }),
      new rspack.LightningCssMinimizerRspackPlugin({
        minimizerOptions: {
          errorRecovery: false,
        },
      }),
    ],
  },
};

#optimization.moduleIds

• Type: false | 'natural' | 'named' | 'deterministic' | 'compact-hashed' | 'hashed'
• Default:production mode is'deterministic', development mode is'named', none mode is'natural'

Tells Rspack which algorithm to use when generating module ids.

The following string values are supported:

We recommend using named in development and deterministic or compact-hashed in production.

Use process.env.NODE_ENV to determine the current environment:

const isDev = process.env.NODE_ENV === 'development';

export default {
  optimization: {
    moduleIds: isDev ? 'named' : 'deterministic',
  },
};

The compact-hashed option uses the shortest available prefix of a stable alphanumeric hash as the module id, balancing long-term caching, bundle size, and runtime performance.

const isDev = process.env.NODE_ENV === 'development';

export default {
  optimization: {
    moduleIds: isDev ? 'named' : 'compact-hashed',
  },
};

#optimization.nodeEnv

• Type: string | false
• Default: Determined by mode:
  • production mode: 'production'
  • development mode: 'development'
  • none mode: false

optimization.nodeEnv controls the value used to replace process.env.NODE_ENV at compile time. Rspack performs this replacement with DefinePlugin.

You can override the mode-dependent default with either of the following values:

• Any string: replace process.env.NODE_ENV with the specified string.
• false: disable the replacement and leave process.env.NODE_ENV unchanged.

export default {
  optimization: {
    nodeEnv: 'production',
  },
};

#optimization.providedExports

• Type: boolean
• Default:true

After enabling, Rspack will analyze which exports the module provides, including re-exported modules. A warning or error will be issued when importing members that reference non-existent exports. By default, optimization.providedExports is enabled. This analysis will increase build time. You may consider disabling this configuration in development mode. Disabling it may lead to errors related to runtime circular dependencies as mentioned in the SideEffects section.

export default {
  optimization: {
    providedExports: false,
  },
};

#optimization.realContentHash

• Type: boolean
• Default:production mode istrue, development mode isfalse

Adds an additional hash compilation pass after the assets have been processed to get the correct asset content hashes. This feature will enable by default in production mode.

If realContentHash is set to false, internal data is used to calculate the hash and it can change when assets are identical in some cases.

export default {
  optimization: {
    realContentHash: true,
  },
};

#optimization.removeEmptyChunks

• Type: boolean
• Default:true

Detect and remove empty chunks generated in the compilation. Setting optimization.removeEmptyChunks to false will disable this optimization.

export default {
  optimization: {
    removeEmptyChunks: false,
  },
};

#optimization.runtimeChunk

• Type: boolean | 'single' | 'multiple' | { name?: string | ((entrypoint: { name: string }) => string) }
• Default:false

Controls whether the Rspack runtime is extracted into separate chunks.

Defaults to false, which means the Rspack runtime code is inlined into the entry chunks.

Setting it to true or 'multiple' will add an additional chunk containing only the Rspack runtime for each entry point. This setting is an alias for:

export default {
  optimization: {
    runtimeChunk: {
      name: (entrypoint) => `runtime~${entrypoint.name}`,
    },
  },
};

Setting it to 'single' will extract the Rspack runtime code of all entry points into a single separate chunk named runtime. This setting is an alias for:

export default {
  optimization: {
    runtimeChunk: {
      name: 'runtime',
    },
  },
};

When optimization.runtimeChunk is an object, its optional name property controls the names of the Rspack runtime chunks.

export default {
  optimization: {
    runtimeChunk: {
      // this will generate a chunk named `my-name.js`
      name: 'my-name',
    },
  },
};

The following configuration defines two entries, pageA and pageB. Suppose both entry files import the same shared.js module, and their generated bundles are loaded on the same HTML page:

export default {
  entry: {
    pageA: './src/page-a.js',
    pageB: './src/page-b.js',
  },
  optimization: {
    runtimeChunk: 'single',
  },
};

Changing runtimeChunk affects the output files and how often shared.js is initialized:

When writing HTML manually, place the runtime file's <script> tag before the entry bundles' tags. HtmlRspackPlugin handles this order automatically. With 'single', both entries share one Rspack runtime and its module cache, so shared.js is initialized only once.

Sharing a Rspack runtime does not extract shared modules into a separate file. Use SplitChunksPlugin to configure module splitting.

#optimization.sideEffects

• Type: boolean | 'flag'
• Default:production mode istrue, development mode is'flag'

If you only want Rspack use the manual sideEffects flag via (package.json and rules[].sideEffects) and don't analyse source code:

export default {
  optimization: {
    sideEffects: 'flag',
  },
};

flag tells Rspack to recognise the sideEffects flag in package.json or rules[].sideEffects to skip over modules which are flagged to contain no side effects when exports are not used.

true tells Rspack not only recognise the sideEffects flag, but also analyse modules which are not flagged explicitly, and determine if they have side effects or not.

export default {
  optimization: {
    sideEffects: true,
  },
};

#optimization.splitChunks

• Type: false | object

Rspack supports splitting chunks with the optimization.splitChunks configuration item.

It is enabled by default for dynamically imported modules.

To turn it off, set it to false.

See available options for configuring this behavior in the SplitChunksPlugin page.

#optimization.usedExports

• Type: boolean | 'global'
• Default:production mode istrue, development mode isfalse

Tells Rspack to determine used exports for each module. This depends on optimization.providedExports. Information collected by optimization.usedExports is used by other optimizations or code generation i.e. Exports are not generated for unused exports, export names are mangled to single char identifiers when all usages are compatible. Dead code elimination in minimizers will benefit from this and can remove unused exports.

export default {
  optimization: {
    usedExports: false,
  },
};

To analyze used exports globally instead of separately for each Rspack runtime:

export default {
  optimization: {
    usedExports: 'global',
  },
};

This page is adapted from webpack documentation under the CC BY 4.0, with modifications.