dev.lazyCompilation#

• Type:

type LazyCompilationOptions =
  | boolean
  | {
      /**
       * Enable lazy compilation for entries.
       */
      entries?: boolean;
      /**
       * Enable lazy compilation for dynamic imports.
       */
      imports?: boolean;
      /**
       * Specify which imported modules should be lazily compiled.
       */
      test?: RegExp | ((m: Module) => boolean);
    };

• Default: false

Used to enable lazy compilation (compilation on demand), implemented based on Rspack's experiments.lazyCompilation.

Introduction#

Lazy compilation is an excellent way to improve dev startup performance. It compiles modules on demand rather than compiling all modules at startup. This means developers can quickly see the application running when they start the dev server and build the necessary modules in stages.

Although Rspack itself has good performance, the overall build time can still be less than ideal when building applications with a large number of modules. This is because the modules in the application need to be compiled by various loaders, such as postcss-loader, sass-loader, vue-loader, etc., which introduce additional compilation overhead.

With lazy compilation enabled, Rspack will only compile the entrypoints and dynamic import modules that are requested. This can significantly reduce the number of modules that are compiled at development startup, improving startup time.

Limitations#

• Lazy compilation is only effective for dev builds.
• Lazy compilation is still an experimental feature in Rspack. In some scenarios, it may not work as expected or may not significantly improve performance.
• Lazy compilation depends on Rspack's local dev server. If you proxy a domain to localhost for development, it will not work properly. So if you need to use a proxy, please disable lazy compilation.

Example#

Enable Lazy Compilation#

export default {
  dev: {
    lazyCompilation: true,
  },
};

This is equivalent to the following configuration:

export default {
  dev: {
    lazyCompilation: {
      imports: true,
      entries: true,
    },
  },
};

Entry Modules#

Use lazyCompilation.entries to control whether to lazily compile entry modules:

export default {
  dev: {
    lazyCompilation: {
      entries: true,
    },
  },
};

With the entries option enabled, Rsbuild will not compile all pages when you start the dev server. Instead, it will only compile a specific page when you visit it.

When lazily compiling entry modules, please note:

• It only applies to multi-page applications (MPA) and does not optimize single-page applications (SPA).
• When you visit a page, you need to wait for the page to finish compiling before you can see its content.

Async Modules#

Use lazyCompilation.imports to control whether to lazily compile dynamic imported modules.

export default {
  dev: {
    lazyCompilation: {
      imports: true,
    },
  },
};

When the imports option is enabled, all async modules will only be compiled when requested. If your project is a single-page application (SPA) and you have split the routes using dynamic import, this will significantly speed up the startup time.