#Code splitting

A good chunk splitting strategy is important for improving application load performance. It leverages 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 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 that automatically splits some commonly used npm packages into chunks of moderate size.
• split-by-module: split by npm package granularity, where each npm package corresponds to a chunk.
• split-by-size: automatically split based on module size.
• all-in-one: bundle all code 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 your application uses the following npm packages, they're 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, improving browser caching efficiency.

#Config

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

#Notes

If the npm packages mentioned above aren't installed or used, the corresponding chunks won't 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 many file requests.
• With HTTP/2, resource loading accelerates and cache hit rates improve due to multiplexing.
• Without HTTP/2, page loading performance may degrade 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

Beyond the built-in strategies, you can customize the splitting strategy for specific needs. Custom strategies have two parts:

• Custom group
• Custom Rspack splitChunks config

You can combine these custom capabilities with built-in strategies: use built-in strategies for common packages and custom functions for 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/,
      },
    },
  },
};

Using the 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

Beyond custom grouping, you can customize Rspack's splitChunks config using 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, see Rspack - splitChunks.

#Using dynamic import for code splitting

Beyond the chunkSplit configuration, dynamic import is another 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.