import WebpackLicense from '@components/WebpackLicense';

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.

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.

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:

export default {
  watchOptions: {
    aggregateTimeout: 600,
  },
};

watchOptions.ignored

• Type: RegExp | string | string[]
• 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.

Since Rspack v1.2.0, .git and node_modules directories are ignored by default, so changes inside them do not trigger rebuilds.

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

export default {
  watchOptions: {
    ignored: /[\\/]\.git[\\/]/,
  },
};

You can also use a glob pattern:

export default {
  watchOptions: {
    ignored: '**/.git',
  },
};

To ignore multiple glob patterns, pass an array:

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:

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. See its documentation for details about the supported pattern syntax.

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().

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:

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.

export default {
  watchOptions: {
    followSymlinks: true,
  },
};

watchOptions.stdin

• Type: boolean

Stop watching when stdin stream has ended.

export default {
  watchOptions: {
    stdin: true,
  },
};