Incremental

incremental controls whether Rspack reuses unaffected intermediate results between compilations in the same long-lived compiler. It is designed for development rebuilds, watch mode, and Hot Module Replacement (HMR), where Rspack knows which files changed and can avoid recalculating unaffected stages and assets.

Here, “development” describes the rebuild workflow, not mode: 'development'. A production-mode watch can also use Incremental. A standalone rspack build is a one-shot build with no previous compilation to update, so incremental does not make separate build invocations incremental.

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

:::tip Incremental artifacts are independent of cache. Disabling cache does not disable incremental rebuilds during development, watch, or HMR. :::

Relationship with cache

cache and incremental are independent options. Cache stores fine-grained computation results in memory or filesystem-backed persistent storage. Incremental recovers prior pass artifacts from the previous compilation, then updates affected work from known mutations.

All four combinations are valid:

Cache	Incremental	Behavior
Off	Off	No state from a prior compilation or build is reused through Cache or Incremental; compilation-local optimizations may still apply.
On	Off	Artifact recovery is disabled, but individual computations can still use memory or persistent cache entries.
Off	On	Development rebuilds recover prior pass artifacts so unaffected portions can be reused, but no fine-grained cache entries are read or written.
On	On	Development rebuilds combine prior-artifact recovery with fine-grained cache hits. This is the normal high-performance development combination.

Cache “On” includes cache: true, cache: { type: 'memory' }, and cache: { type: 'persistent' }.

Rspack Incremental has a similar optimization goal to webpack's cacheUnaffected: avoid recomputing work that is unaffected by a change. Rspack applies the idea to multiple compilation stages and exposes it independently from Cache. This is semantic alignment, not configuration equivalence: webpack requires cacheUnaffected to be used with memory cache, while Rspack exposes incremental as an independent top-level option.

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.

Value	Behavior
`false` / `'none'`	Disable incremental builds for all stages.
`'safe'`	Enable incremental builds only for the `buildModuleGraph`, `buildChunkGraph`, and `emitAssets` stages.
`true` / `'advance-silent'`	Enable all incremental stages and silently handle cases that are not friendly to incremental builds. This is the default behavior of Rspack.
`'advance'`	Enable the same stages as `'advance-silent'`, but emit warnings when configuration or plugin behavior causes Rspack to disable incremental passes. This helps identify what is limiting incremental build performance.

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.

In object configuration, omitted stage options default to true, and silent also defaults to true. For example, { modulesCodegen: false } disables only that stage; the other Incremental stages remain enabled.

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 improves rebuilds and HMR when a previous compilation and a known change set are available. It does not make the initial compilation or a separate one-shot build incremental.

Memory or persistent Cache may independently speed up computations during either an initial build or a rebuild. In particular, a filesystem Cache hit after process startup is Cache acceleration, not an incremental build.