# Source: https://rspack.dev/config/incremental.md

# Incremental

[Added in v1.1.0-beta.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.1.0-beta.0)
Whether to enable incremental build, which significantly speeds up rebuilds and HMR by only rebuilding the changed parts.

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

Two configuration ways are provided:

1. Presets: including `boolean | 'none' | 'safe' | 'advance' | 'advance-silent'`
   - `false | 'none'`: Disable incremental, and it will not be enabled for any stage.
   - `'safe'`: Enable incremental for the `buildModuleGraph` and `emitAssets` stages.
   - `true | 'advance-silent'`: Enable incremental for all stages to maximize performance for rebuilds and HMR. This is the default behavior of Rspack.
   - `'advance'`: The same as above, but it will detect cases that are unfriendly to incremental and throw warnings to users (e.g., incorrect configurations). This option can help you to identify potential issues affecting incremental build performance.
2. **Detailed object configuration**: `Incremental`, which allows fine-grained control over whether the incremental is enabled for each stage.

   {/* prettier-ignore */}

   <details>
     <summary style={{ display: 'list-item' }}>
       Detailed type of 

       `Incremental`
     </summary>

     <blockquote>
       <p>
         ```ts
         type Incremental = {
           // Whether to throw a warning when encountering situations that are not friendly for incremental.
           silent?: boolean;
           // The following configuration is used to control whether the incremental of each stage is enabled.
           buildModuleGraph?: boolean;
           finishModules?: boolean;
           optimizeDependencies?: boolean;
           buildChunkGraph?: boolean;
           moduleIds?: boolean;
           chunkIds?: boolean;
           modulesHashes?: boolean;
           modulesCodegen?: boolean;
           modulesRuntimeRequirements?: boolean;
           chunksRuntimeRequirements?: boolean;
           chunksHashes?: boolean;
           chunkAsset?: boolean;
           emitAssets?: boolean;
         };
         ```
       </p>
     </blockquote>
   </details>

Usually, we recommend configuring in the preset way, and the detailed object configuration is only provided to facilitate bug troubleshooting.

Incremental only improves the rebuild performance and have no impact on the initial build. However, when persistent cache is available, initial builds are also treated as rebuilds too, and can benefit from incremental for performance.

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

| how to build | incremental speed up |
| :----------: | :------------------: |
|   hot build  |           ✅          |
|  cold build  |           ❌          |
|   hot start  |           ✅          |
|  cold start  |           ❌          |
|  rebuild/HMR |           ✅          |

Starting from v1.4.0, Rspack enables incremental builds using `'advance-silent'` mode by default. In previous versions, it only activated incremental builds for the `buildModuleGraph` and `emitAssets` phase by default with `'safe'` mode.