The content of this section is derived from the content of the following links and is subject to the CC BY 4.0 license.
The following contents can be assumed to be the result of modifications and deletions based on the original contents if not specifically stated.
Out of the box SplitChunksPlugin
should work well for most users.
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:
When trying to fulfill the last two conditions, bigger chunks are preferred.
Rspack provides a set of options for developers that want more control over this functionality.
The default configuration was chosen to fit web performance best practices, but the optimal strategy for your project might differ. If you're changing the configuration, you should measure the effect of your changes to ensure there's a real benefit.
This configuration object represents the default behavior of the SplitChunksPlugin
.
When files paths are processed by Rspack, they always contain /
on UNIX systems and \
on Windows. That's why using [\\/]
in {cacheGroup}.test
fields is necessary to represent a path separator. /
or \
in {cacheGroup}.test
will cause issues when used cross-platform.
Passing an entry name to {cacheGroup}.test
and using a name of an existing chunk for {cacheGroup}.name
is no longer allowed.
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
.
'initial' | 'all' | 'async' | RegExp | ((chunk: Chunk) => bool)
'async'
This indicates which chunks will be selected for optimization.
When a string is provided, valid values are all
, async
, and initial
. Providing all
can be particularly powerful, because it means that chunks can be shared even between async and non-async chunks.
Alternatively, you may provide a function for more control. The return value will indicate whether to include each chunk.
You can also pass a regular expression, which is a short for (chunk) => regex.test(chunk.name)
.
number
30
Maximum number of parallel requests when on-demand loading.
number
30
Maximum number of parallel requests at an entry point.
number
1
The minimum times must a module be shared among chunks before splitting.
boolean
true
if options.mode
is 'production'
, otherwise defaults to false
Prevents exposing path info when creating names for parts splitted by maxSize.
number | Record<string, number>
20000
in production and 10000
in othersMinimum size, in bytes, for a chunk to be generated.
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.
maxSize
takes higher priority than maxInitialRequest/maxAsyncRequests
. Actual priority is maxInitialRequest/maxAsyncRequests < maxSize < minSize
.
Setting the value for maxSize
sets the value for both maxAsyncSize
and maxInitialSize
.
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.
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.
string
-
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.
string | function
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.cacheGroups.{cacheGroup}.name
can be used to move modules into a chunk that is a parent of the source chunk. For example, use name: "entry-name"
to move modules into the entry-name
chunk. You can also use on demand named chunks, but you must be careful that the selected modules are only used under this chunk.
boolean
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
.
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.
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
.
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
.
number
-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).
RegExp | string | function
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.
boolean
Tells Rspack to ignore splitChunks.minSize
, splitChunks.minChunks
, splitChunks.maxAsyncRequests
and splitChunks.maxInitialRequests
options and always create chunks for this cache group.
string
Sets the hint for chunk id. It will be added to chunk's filename.
string
Allows to override the filename when and only when it's an initial chunk. All placeholders available in output.filename are also available here.
boolean
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:
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.