#Code splitting

A good chunk splitting strategy is important for improving application loading performance. It can leverage browser caching to reduce requests and improve loading speed.

Several chunk splitting strategies are built into Rsbuild to meet the needs of most applications. You can also customize the chunk splitting configuration for specific use cases.

See Rspack - Code Splitting for more details.

#Strategies

The chunk splitting configuration of Rsbuild is in performance.chunkSplit.

Rsbuild supports the following chunk splitting strategies:

• split-by-experience: an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.
• split-by-module: split by NPM package granularity, each NPM package corresponds to a chunk.
• split-by-size: automatically split according to module size.
• all-in-one: bundle all codes into one chunk.
• single-vendor: bundle all NPM packages into a single chunk.
• custom: custom chunk splitting strategy.

#split-by-experience

#Behavior

Rsbuild uses the split-by-experience strategy by default, an optimization strategy based on practical experience. When the following npm packages are used in your application, they are automatically split into separate chunks:

• lib-polyfill.js: Contains core-js, @swc/helpers, tslib
• lib-axios.js: Contains axios
• lib-react.js: Provided by @rsbuild/plugin-react
• lib-vue.js: Provided by @rsbuild/plugin-vue

This approach groups commonly used packages and splits them into individual chunks, which helps improve browser caching efficiency.

#Config

export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
    },
  },
};

#Notes

If the npm packages mentioned above are not installed or used, the corresponding chunks will not be generated.

#split-by-module

#Behavior

Split each npm package into a separate chunk.

#Config

export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-module',
    },
  },
};

#Notes

• This configuration splits node_modules into many smaller chunks, resulting in a large number of file requests.
• With HTTP/2, resource loading is accelerated and cache hit rates improve due to multiplexing.
• Without HTTP/2, page loading performance may decrease due to HTTP head-of-line blocking. Use with caution.

#all-in-one

#Behavior

This strategy puts all source code and third-party dependencies in a single chunk.

#Config

export default {
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
};

#Notes

• This configuration bundles all generated JS code into a single file (except dynamically imported chunks).
• The single JS file may be very large, potentially reducing page loading performance.

To also bundle dynamically imported chunks into a single file, set the output.asyncChunks option in Rspack to false:

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
      },
    },
  },
});

#single-vendor

#Behavior

This strategy puts third-party dependencies in one chunk and source code in another.

#Config

export default {
  performance: {
    chunkSplit: {
      strategy: 'single-vendor',
    },
  },
};

#Notes

The single vendor file may be very large, potentially reducing page loading performance.

#split-by-size

#Behavior

With this strategy, after setting minSize and maxSize to fixed values, Rsbuild will automatically split chunks without extra configuration.

#Config

export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 30000,
      maxSize: 50000,
    },
  },
};

#Custom splitting strategy

In addition to built-in strategies, you can also customize the splitting strategy for more specific needs. Custom strategies have two parts:

• Custom group
• Custom Rspack splitChunks config

Note that these custom capabilities can be used together with built-in strategies; you can use built-in strategies to split common packages and custom functions to split other packages.

#Custom group

Rsbuild supports custom groups, which are more flexible than built-in strategies and simpler than writing Rspack's splitChunks config.

For example, split the axios library under node_modules into axios.js:

export default {
  performance: {
    chunkSplit: {
      forceSplitting: {
        axios: /node_modules[\\/]axios/,
      },
    },
  },
};

Through forceSplitting config, you can easily split packages into chunks.

#Notes

Chunks split using forceSplitting are inserted into the HTML file as initial resources using <script> tags. Split them appropriately based on your scenario to avoid excessive initial bundle size.

#Custom config

In addition to custom grouping, you can also customize Rspack's splitChunks config through override. For example:

• Set minSize to 30,000 so modules smaller than 30,000 bytes will not be split.

export default {
  performance: {
    chunkSplit: {
      override: {
        chunks: 'all',
        minSize: 30000,
      },
    },
  },
};

• Bundle all CSS files into a single styles.css.

export default {
  performance: {
    chunkSplit: {
      override: {
        cacheGroups: {
          styles: {
            name: 'styles',
            minSize: 0,
            chunks: 'all',
            test: /\.(?:css|less|sass|scss|styl)$/,
            priority: 99,
          },
        },
      },
    },
  },
};

The override config will be merged with Rspack's splitChunks config. For specific config details, please refer to Rspack - splitChunks.

#Using dynamic import for code splitting

In addition to the chunkSplit configuration, using dynamic import is also an important optimization technique that can effectively reduce initial bundle size.

When the bundler encounters import() syntax, it automatically splits the relevant code into a new chunk and loads it on-demand at runtime.

For example, if your project has a large module called bigModule.ts (which can also be a third-party dependency), you can use dynamic import to load it on-demand:

// Somewhere in your code where you need to use bigModule
import('./bigModule.ts').then((bigModule) => {
  // Use bigModule here
});

When you run the build command, bigModule.ts will be automatically split into a new chunk and loaded on-demand at runtime.