Incremental

incremental controls Rspack's incremental build capability. When enabled, Rspack reuses unaffected intermediate results during rebuilds and Hot Module Replacement (HMR), and only recalculates the stages and assets affected by the change.

• Type: boolean | 'none' | 'safe' | 'advance' | 'advance-silent' | Incremental
• Default: 'advance-silent'

:::tip When cache is disabled, Rspack disables the incremental build stages. Keep cache enabled if you want to use incremental builds during development, watch, or HMR. :::

Configuration

incremental can be configured with presets or a detailed object.

Most projects can use the default value; configure this option explicitly only when you need to disable incremental builds, fall back to a more conservative strategy, or diagnose incremental build issues.

Examples

By default, you do not need to configure incremental explicitly. To surface warnings when configuration or plugin behavior disables incremental passes during development, use 'advance':

export default {
  incremental: 'advance',
};

You can also configure incremental with an object to control each build stage individually. Object configuration is mainly intended for debugging or temporary workarounds; presets are recommended for normal usage.

export default {
  incremental: {
    silent: false,
    modulesCodegen: false,
  },
};

Type definition

type Incremental = {
  // Whether to suppress warnings for cases that are not friendly to incremental builds.
  // Set this to false to emit warnings.
  silent?: boolean;
  // The following options control whether incremental builds are enabled for each stage.
  buildModuleGraph?: boolean;
  finishModules?: boolean;
  optimizeDependencies?: boolean;
  buildChunkGraph?: boolean;
  optimizeChunkModules?: boolean;
  moduleIds?: boolean;
  chunkIds?: boolean;
  modulesHashes?: boolean;
  modulesCodegen?: boolean;
  modulesRuntimeRequirements?: boolean;
  chunksRuntimeRequirements?: boolean;
  chunksHashes?: boolean;
  chunkAsset?: boolean;
  emitAssets?: boolean;
};

Performance impact

Incremental builds mainly improve rebuilds and HMR when reusable compilation state already exists. They do not make an initial build faster when no state can be reused.

When persistent cache is enabled and hit, Rspack can restore part of the compilation state from cache, so the build after startup can also benefit from incremental builds.

The table below shows the results of incremental in different scenarios:

In the table, "hot" means reusable compilation state or persistent cache is available, while "cold" means no reusable state is available.