#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.

Incremental is enabled only when mode is set to 'development'. 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'

#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 “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.

#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 {
  mode: 'development',
  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, but the initial compilation can still prepare artifacts for a later rebuild.

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.