#dev.watchFiles

• Type:

type WatchFileEvent = 'add' | 'change' | 'unlink';

type WatchFiles = {
  paths: string | string[];
  events?: WatchFileEvent[];
  type?: 'reload-page' | 'restart' | 'reload-server';
  // watch options for chokidar
  options?: ChokidarOptions;
};

type WatchFilesConfig = WatchFiles | WatchFiles[];

• Default: undefined

Watch specified files and directories for changes. When a change is detected, it can trigger a page reload or restart the dev server or watch build.

#paths

• Type: string | string[]
• Default: undefined

Paths of the files or directories to watch, supports glob syntax. It can be a single path or an array of multiple paths.

• Watching a single file:

export default {
  dev: {
    watchFiles: {
      paths: 'public/demo.txt',
    },
  },
};

• Using glob to match multiple files:

export default {
  dev: {
    watchFiles: {
      paths: 'src/**/*.txt',
    },
  },
};

• Watching multiple file paths:

export default {
  dev: {
    watchFiles: {
      paths: ['src/**/*.txt', 'public/**/*'],
    },
  },
};

#events

• Type: ('add' | 'change' | 'unlink')[]
• Default: ['add', 'change', 'unlink']

Specifies the file events that trigger the configured action:

• add: A watched file is detected. By default, only files that appear after the watcher starts trigger this event. If options.ignoreInitial is false, existing files also trigger it during startup.
• change: A watched file changes.
• unlink: A watched file disappears.

For example, to restart only when files are added to or removed from a directory:

export default {
  dev: {
    watchFiles: {
      paths: './config',
      type: 'restart',
      events: ['add', 'unlink'],
    },
  },
};

#type

• Type: 'reload-page' | 'restart' | 'reload-server'
• Default: 'reload-page'

Specifies whether to trigger a page reload or restart the dev server or watch build when a file changes.

#reload-page

reload-page means that when a watched file event specified by events occurs, the page in the browser automatically reloads. By default, additions, changes, and removals all trigger a reload. If type is not explicitly specified, Rsbuild uses reload-page.

This can be used to watch changes to static assets, such as files in the public directory.

export default {
  dev: {
    watchFiles: {
      type: 'reload-page',
      paths: 'public',
    },
  },
};

If both dev.hmr and dev.liveReload are set to false, the page will not automatically reload.

#restart

restart requests a dev server restart when running rsbuild dev, or a watch build restart when running rsbuild build --watch.

This can be used to watch configuration files whose changes require Rsbuild to be reinitialized.

For example, if you maintain some common configuration files in the config directory, such as common.ts, you may want changes to these files to restart the dev server or watch build:

import { commonConfig } from './config/common';

export default {
  ...commonConfig,
  dev: {
    watchFiles: {
      type: 'restart',
      paths: ['./config/*.ts'],
    },
  },
};

For details about automatic config file watching and restart behavior, see Configuration file watching.

#reload-server

reload-server is a deprecated alias for restart. It remains supported for backward compatibility.

#options

• Type: ChokidarOptions
• Default: undefined

watchFiles is implemented based on chokidar v4, and you can pass chokidar options through options.

export default {
  dev: {
    watchFiles: {
      paths: 'src/**/*.txt',
      options: {
        usePolling: false,
      },
    },
  },
};

#Notes

watchFiles is not applicable for watching build dependency files. When an Rsbuild build starts, the underlying Rspack automatically watches all build dependencies. Any changes to these files will trigger a new build.

If you want to prevent some files from triggering a rebuild when they change, you can use Rspack's watchOptions.ignored configuration item.

See HMR - File Watching for details.

#Version history