#dev.watchFiles

• Type:

type WatchFiles = {
  paths: string | string[];
  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/**/*'],
    },
  },
};

#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 file changes, the page in the browser will automatically reload. If the type is not explicitly specified, Rsbuild defaults to the reload-page behavior.

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'],
    },
  },
};

When using the JavaScript API, rsbuild.startDevServer(), rsbuild.createDevServer(), and rsbuild.build({ watch: true }) install restart watchers, while regular builds and preview servers do not. When a watched file changes, Rsbuild calls the onRestart hook. By default, Rsbuild does not close or restart the current task; you can pass the restart option to handle restart requests.

#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