#SplitChunksPlugin

SplitChunksPlugin is a built-in plugin that splits code into multiple chunks to optimize application loading performance and achieve better caching strategies and parallel loading.

SplitChunksPlugin can be configured through the optimization.splitChunks option, and you typically don't need to manually register this plugin.

#Default behavior

Rspack has a built-in configuration for SplitChunksPlugin that works well for most scenarios.

By default it only affects on-demand chunks, because changing initial chunks would affect the script tags the HTML file should include to run the project.

Rspack will automatically split chunks based on these conditions:

• New chunk can be shared OR modules are from the node_modules folder
• New chunk would be bigger than 20kb (before min+gz)
• Maximum number of parallel requests when loading chunks on demand would be lower or equal to 30
• Maximum number of parallel requests at initial page load would be lower or equal to 30

When trying to fulfill the last two conditions, bigger chunks are preferred.

#Options

Rspack provides a set of options for developers that want more control over this functionality.

#optimization.splitChunks

This configuration object represents the default behavior of the SplitChunksPlugin.

export default {
  //...
  optimization: {
    splitChunks: {
      chunks: 'async',
      minChunks: 1,
      minSize: 20000,
      maxAsyncRequests: 30,
      maxInitialRequests: 30,
      cacheGroups: {
        defaultVendors: {
          test: /[\\/]node_modules[\\/]/,
          priority: -10,
          reuseExistingChunk: true,
        },
        default: {
          minChunks: 2,
          priority: -20,
          reuseExistingChunk: true,
        },
      },
    },
  },
};

#splitChunks.cacheGroups

Cache groups can inherit and/or override any options from splitChunks.{cacheGroup}.*; but test, priority and reuseExistingChunk can only be configured on cache group level. To disable any of the default cache groups, set them to false.

export default {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        default: false,
      },
    },
  },
};

#splitChunks.chunks

#splitChunks.cacheGroups.{cacheGroup}.chunks

• Type:

type OptimizationSplitChunksChunks =
  | 'initial'
  | 'async'
  | 'all'
  | RegExp
  | ((chunk: Chunk) => boolean);

• Default: 'async'

This option controls which chunks should be selected for code splitting. When a string is provided, the possible values are all, async and initial.

• all: Split all types of chunks, including initial chunks and async chunks.
• initial: Only split initial chunks.
• async: Only split async chunks.

Generally, setting it to all can help reduce duplicate modules being bundled, as it means chunks can be shared between initial chunks and async chunks.

export default {
  optimization: {
    splitChunks: {
      // include all types of chunks
      chunks: 'all',
    },
  },
};

The chunks option can be set to a regular expression, which is a shorthand for (chunk) => typeof chunk.name === "string" && regex.test(chunk.name).

export default {
  optimization: {
    splitChunks: {
      // equivalent to `chunks: (chunk) => typeof chunk.name === "string" && /foo/.test(chunk.name)`
      chunks: /foo/,
    },
  },
};

The chunks option can be set to a function for more fine-grained control. The function receives a chunk parameter, and returning true means the chunk participates in splitting (modules within it may be extracted into new chunks), while returning false means the chunk doesn't participate in splitting (remains as is).

export default {
  optimization: {
    splitChunks: {
      chunks(chunk) {
        // exclude `foo` chunk
        return chunk.name !== 'foo';
      },
    },
  },
};

You can configure chunks individually for each cacheGroup, for example:

export default {
  optimization: {
    splitChunks: {
      cacheGroups: {
        groupA: {
          chunks: 'all',
        },
        groupB: {
          chunks: 'initial',
        },
        groupC: {
          chunks: 'async',
        },
      },
    },
  },
};

#splitChunks.maxAsyncRequests

• Type: number
• Default: 30

Maximum number of parallel requests when on-demand loading.

#splitChunks.maxInitialRequests

• Type: number
• Default: 30

Maximum number of parallel requests at an entry point.

#splitChunks.minChunks

#splitChunks.cacheGroups.{cacheGroup}.minChunks

• Type: number
• Default: 1

The minimum times must a module be shared among chunks before splitting.

#splitChunks.hidePathInfo

• Type: boolean
• Default: defaults to true if options.mode is 'production', otherwise defaults to false

Prevents exposing path info when creating names for parts splitted by maxSize.

#splitChunks.minSize

#splitChunks.cacheGroups.{cacheGroup}.minSize

• Type: number | Record<string, number>
• Default: 20000 in production and 10000 in others

When using the number type of configuration, the same minSize will be configured for all module types defined in splitChunks.defaultSizeTypes.

export default {
  //...
  optimization: {
    splitChunks: {
      minSize: 100 * 1000,
    },
  },
};

When configured with the object form, different minSize can be set for different types of module types defined in splitChunks.defaultSizeTypes.

export default {
  //...
  optimization: {
    splitChunks: {
      minSize: {
        javascript: 100 * 1000,
        css: 300 * 1000,
      },
    },
  },
};

For example, the above configuration means that the minimum size of javascript modules in the split chunks needs to be at least 100KB, and the minimum size of css modules needs to be at least 300KB.

#splitChunks.minSizeReduction

#splitChunks.cacheGroups.{cacheGroup}.minSizeReduction

• **Type: ** number | Record<string, number>
• Default: 0

If there are several small modules in the build output, developers may not want to generate separate chunks for them even if their total size exceeds the minSize threshold. In this case, you can use the minSizeReduction parameter to set the minimum size reduction threshold required for module splitting.

The calculation rule for this parameter is: splitting will only occur when the total size reduction across all parent chunks after splitting the module is not less than the specified value.

Assuming the following scenario, suppose there is a 40KB module that is referenced by 2 chunks, and we set minSizeReduction: 100. If we were to split this module, each parent chunk would be reduced by 40KB, resulting in a total reduction of 40KB × 2 = 80KB. As this is less than 100KB, the split will not be triggered.

export default {
  //...
  optimization: {
    splitChunks: {
      minSizeReduction: 100 * 1000,
    },
  },
};

#splitChunks.maxSize

number | Record<string, number> = 0

Using maxSize (either globally optimization.splitChunks.maxSize per cache group optimization.splitChunks.cacheGroups[x].maxSize or for the fallback cache group optimization.splitChunks.fallbackCacheGroup.maxSize) tells Rspack to try to split chunks bigger than maxSize bytes into smaller parts. Parts will be at least minSize (next to maxSize) in size. The algorithm is deterministic and changes to the modules will only have local effects. So that it is usable when using long term caching and doesn't require records. maxSize is only a hint and could be violated when modules are bigger than maxSize or splitting would violate minSize.

When the chunk has a name already, each part will get a new name derived from that name. Depending on the value of optimization.splitChunks.hidePathInfo it will add a key derived from the first module name or a hash of it.

maxSize option is intended to be used with HTTP/2 and long term caching. It increases the request count for better caching. It could also be used to decrease the file size for faster rebuilding.

#splitChunks.maxAsyncSize

number | Record<string, number>

Like maxSize, maxAsyncSize can be applied globally (splitChunks.maxAsyncSize), to cacheGroups (splitChunks.cacheGroups.{cacheGroup}.maxAsyncSize), or to the fallback cache group (splitChunks.fallbackCacheGroup.maxAsyncSize).

The difference between maxAsyncSize and maxSize is that maxAsyncSize will only affect on-demand loading chunks.

#splitChunks.maxInitialSize

number | Record<string, number>

Like maxSize, maxInitialSize can be applied globally (splitChunks.maxInitialSize), to cacheGroups (splitChunks.cacheGroups.{cacheGroup}.maxInitialSize), or to the fallback cache group (splitChunks.fallbackCacheGroup.maxInitialSize).

The difference between maxInitialSize and maxSize is that maxInitialSize will only affect initial load chunks.

#splitChunks.automaticNameDelimiter

• Type: string
• Default: -

By default Rspack will generate names using origin and name of the chunk (e.g. vendors-main.js).

This option lets you specify the delimiter to use for the generated names.

#splitChunks.name

#splitChunks.cacheGroups.{cacheGroup}.name

• Type: string | function
• Default: false

where the version of the function type is >=0.4.1.

Also available for each cacheGroup: splitChunks.cacheGroups.{cacheGroup}.name.

The name of the split chunk. Providing false will keep the same name of the chunks so it doesn't change names unnecessarily. It is the recommended value for production builds.

Providing a string allows you to use a custom name. Specifying a string will merge all common modules and vendors into a single chunk. This might lead to bigger initial downloads and slow down page loads.

If the splitChunks.name matches an entry point name, the entry point will be removed.

#splitChunks.filename

#splitChunks.cacheGroups.{cacheGroup}.filename

• Type: string | function

Allows to override the filename when and only when it's an initial chunk. All placeholders available in output.filename are also available here.

export default {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          filename: 'vendors-[name].js',
          // or
          filename: (pathData, assetInfo) => {
            return `${pathData.chunk.name}-bundle.js`;
          },
        },
      },
    },
  },
};

#splitChunks.usedExports

• Type: boolean
• Default: Value of optimization.usedExports

Enabling this configuration, the splitting of chunks will be grouped based on the usage of modules exports in different runtimes, ensuring the optimal loading size in each runtime.

For example, if there are three entry points named foo, bar, and baz, they all depend on the same module called shared. However, foo and bar depend on the export value1 from shared, while baz depends on the export value2 from shared.

import { value1 } from 'shared';
value1;

import { value1 } from 'shared';
value1;

import { value2 } from 'shared';
value2;

In the default strategy, the shared module appears in 3 chunks. If it meets the minSize for splitting, then the shared module should be extracted into a separate chunk.

chunk foo, chunk bar
      \
      chunk shared (exports value1 and value2)
      /
chunk baz

However, this would result in none of the three entry points having the optimal loaded size. Loading the shared module from the foo and bar entries would unnecessarily load the export value2, while loading from the baz entry would unnecessarily load the export value1.

When the splitChunks.usedExports optimization is enabled, it analyzes which exports of the shared module are used in different entries. It finds that the exports used in foo and bar are different from those in baz, resulting in the creation of two distinct chunks, one corresponding to the entries foo and bar, and the other corresponding to the entry baz.

chunk foo, chunk bar
        \
      chunk shared-1 (exports only value1)

chunk baz
        \
      chunk shared-2 (exports only value2)

#splitChunks.defaultSizeTypes

• Type: string[]
• Default: ["javascript", "unknown"], and if experiments.css is enabled, it will also include "css"

When calculating the size of chunks, only the sizes of javascript modules and built-in css modules are taken into account by default. For example, when configuring minSize: 300, both javascript modules and css modules need to meet the requirement in order to be split.

You can configure additional module types, for example, if you want WebAssembly modules to be split as well:

export default {
  optimization: {
    splitChunks: {
      defaultSizeTypes: ['wasm', '...'],
    },
  },
};

#splitChunks.cacheGroups

Cache groups can inherit and/or override any options from splitChunks.*; but test, priority and reuseExistingChunk can only be configured on cache group level. To disable any of the default cache groups, set them to false.

export default {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        default: false,
      },
    },
  },
};

#splitChunks.cacheGroups.{cacheGroup}.priority

• Type: number
• Default: -20

A module can belong to multiple cache groups. The optimization will prefer the cache group with a higher priority. The default groups have a negative priority to allow custom groups to take higher priority (default value is 0 for custom groups).

#splitChunks.cacheGroups.{cacheGroup}.test

• Type: RegExp | string | (module: Module, { chunkGraph: ChunkGraph, moduleGraph: ModuleGraph }) => boolean

where the version of the function type is >=0.4.1.

Controls which modules are selected by this cache group. Omitting it selects all modules. It can match the absolute module resource path or chunk names. When a chunk name is matched, all modules in the chunk are selected.

#splitChunks.cacheGroups.{cacheGroup}.enforce

• Type: boolean

Tells Rspack to ignore splitChunks.minSize, splitChunks.minChunks, splitChunks.maxAsyncRequests and splitChunks.maxInitialRequests options and always create chunks for this cache group.

#splitChunks.cacheGroups.{cacheGroup}.idHint

• Type: string

Sets the hint for chunk id. It will be added to chunk's filename.

#splitChunks.cacheGroups.{cacheGroup}.reuseExistingChunk

• Type: boolean
• Default false

Whether to reuse existing chunks when possible. If so, after splitting, the newly created chunk contains modules that are exactly the same as those in the original chunk, the original chunk will be reused, and no new chunk will be generated, which may affect the final filename of the chunk. For example:

chunk Foo: [ module A, module B ]
chunk Bar: [ module B ]

cacheGroup: {
  test: /B/,
  chunks: 'all'
}

In chunks Foo and Bar, the module B, due to the configuration of cacheGroup, will be split into a new chunk that only contains module B. This new chunk is identical in terms of the modules it contains with chunk Bar, so chunk Bar can be directly reused.

If the setting of reuseExistingChunk is set to false, then the module B in chunks Bar and Foo will be moved to a new chunk, and chunk Bar, since it no longer contains any modules, will be deleted as an empty chunk.

#splitChunks.cacheGroups.{cacheGroup}.type

• Types: string | RegExp

Allows to assign modules to a cache group by module type.