dev.watchFiles#

• Type:

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

type WatchFilesConfig = WatchFiles | WatchFiles[];

• Default: undefined

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

paths#

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

Paths of the files or directories to be watched, 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' | 'reload-server'
• Default: 'reload-page'

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

reload-page#

reload-page means that when a file changes, the page opened in the browser will automatically reload. If the type is not explicitly specified, Rsbuild will default 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.

reload-server#

reload-server means that the dev server will automatically restart when a file changes. This can be used to watch changes to configuration files, such as modules imported by the rsbuild.config.ts file.

For example, if you maintain some common configuration files in the config directory, such as common.ts, you want the dev server to automatically restart when these files change. Example configuration:

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

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

It should be noted that the reload-server functionality is provided by Rsbuild CLI. If you are using a custom server or an upper-layer framework based on the Rsbuild, this configuration is currently not supported.

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 will 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 more details.