> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Watch

Rspack can watch files and recompile whenever they change.

## watch

- **Type:** `boolean`
- **Default:** `false`

Turn on watch mode. This means that after the initial build, Rspack will continue to watch for changes in any of the resolved files.

```js title="rspack.config.mjs"
export default {
  watch: true,
};
```

:::tip
`watch` is enabled by default when using `@rspack/dev-server`.
:::

## watchOptions

- **Type:** `object`

A set of options used to customize watch mode.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: /node_modules/,
    poll: true,
  },
};
```

### watchOptions.aggregateTimeout

- **Type:** `number`
- **Default:** `5`

Add a delay before rebuilding once the first file changed. This allows Rspack to aggregate any other changes made during this time period into one rebuild. Pass a value in milliseconds:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    aggregateTimeout: 600,
  },
};
```

### watchOptions.ignored

- **Type:** `RegExp | string | string[] | ((entry: string) => boolean)`
- **Default:** `/[\\/](?:\.git|node_modules)[\\/]/`

Use `watchOptions.ignored` to exclude matching files and directories from watch mode. Ignoring directories that do not need to be watched can reduce CPU and memory usage.

By default, `.git` and `node_modules` directories are ignored, so changes inside them do not trigger rebuilds.

To watch files in `node_modules`, override the default value and ignore only the `.git` directory:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: /[\\/]\.git[\\/]/,
  },
};
```

You can also use a glob pattern:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: '**/.git',
  },
};
```

To ignore multiple glob patterns, pass an array:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: ['**/files/**/*.js', '**/.git', '**/node_modules'],
  },
};
```

You can also specify one or more absolute paths. Because strings are interpreted as glob patterns, normalize path separators to forward slashes for consistent behavior across platforms:

```js title="rspack.config.mjs"
import path from 'node:path';

const ignoredDir = path
  .resolve(import.meta.dirname, 'ignored-dir')
  .replaceAll(path.sep, '/');

export default {
  watchOptions: {
    ignored: [ignoredDir],
  },
};
```

The glob syntax used by `watchOptions.ignored` is based on [glob-to-regexp](https://github.com/fitzgen/glob-to-regexp). See its documentation for details about the supported pattern syntax.

Finally, `ignored` can be a function that is asked about every entry and returns `true` to exclude it:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: (entry) => entry.includes('.git'),
  },
};
```

Unlike the other forms, the function receives the entry with the platform path separators, and it has to exclude the entries below an excluded directory itself.

### watchOptions.poll

- **Type:** `number | boolean`
- **Default:** `false`

Whether to watch by polling.

When set to `true`, the default polling interval is 5007 milliseconds. This matches the default polling interval used by Node.js `fs.watchFile()`.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    poll: true,
  },
};
```

You can also set a custom polling interval. Note that shorter intervals can significantly increase CPU usage and file system I/O:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    poll: 1000, // Check for changes every second
  },
};
```

### watchOptions.followSymlinks

- **Type:** `boolean`
- **Default:** `false`

Follow symbolic links while looking for a file. This is usually not needed as Rspack already resolves symlinks with [resolve.symlinks](/config/resolve.md#resolvesymlinks).

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    followSymlinks: true,
  },
};
```

### watchOptions.stdin

- **Type:** `boolean`

Stop watching when stdin stream has ended.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    stdin: true,
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/watch) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.