#CssChunkingPlugin

CssChunkingPlugin is an experimental plugin specifically designed for CSS module code splitting (inspired by Next.js). It ensures that the execution order of styles matches the import order in your source code, preventing style issues.

new rspack.experiments.CssChunkingPlugin(options);

#Options

#strict

• Type: boolean
• Default: false

Whether to strictly preserve the import order of CSS modules.

#Mode comparison

#Normal mode (strict: false, default)

new rspack.experiments.CssChunkingPlugin({
  strict: false,
});

• If CSS modules are imported in different orders throughout the project, they are considered to have no dependencies between them.
• Allow merging independent CSS modules into the same chunk to reduce the number of chunks.

#Strict mode (strict: true)

new rspack.experiments.CssChunkingPlugin({
  strict: true,
});

• Strictly ensures that the execution order of CSS modules matches the import order in the source code.

#Example

a.css and b.css are imported in foo.js and bar.js with different sequences:

// foo.js
import './a.css';
import './b.css';

// bar.js
import './b.css';
import './a.css';

Regular Mode (strict: false): Considers a.css and b.css to have no dependency relationship and doesn't enforce execution order, thus merging them into the same chunk.

Strict Mode (strict: true): Strictly maintains execution order consistent with import sequence, therefore packaging a.css and b.css into separate chunks

#Differences from SplitChunksPlugin

SplitChunksPlugin does not consider the import order of modules when splitting code. For JavaScript modules, this is not an issue because execution order is determined at runtime via function calls.

However, for CSS modules, the execution order is entirely determined by their order in the output files and cannot be controlled at runtime. If the order changes, it may cause style issues.

For example, importing the following CSS modules:

import './a.css';
import './b.css';
import './c.css';

SplitChunksPlugin may split them into the following chunks to satisfy maxSize or other constraints:

chunk-1: b.css
chunk-2: a.css, c.css  // may be split due to large size

This results in the execution order being b.css → a.css → c.css, which violates the original import order and may cause style errors.

CssChunkingPlugin first splits all CSS modules, then determines which can be merged based on the import order in the source code. Modules that cannot be merged are split into separate chunks to ensure style correctness.