fix(v2): docusaurus start --poll 500 should work + better config load failure error (#3622)

* start --poll 500 should be accepted + better error message when siteDir is wrongly passed as a cli arg and lead to config loading failure

* docusaurus start --poll 500  option should also be used for chokidar

* config error message: relative path for reliable tests

* update snapshot

* document start --poll [interval]

packages/docusaurus-types/src/index.d.ts

@@ -101,7 +101,7 @@ export type HostPortCLIOptions = {
 export type StartCLIOptions = HostPortCLIOptions & {
   hotOnly: boolean;
   open: boolean;
-  poll: boolean;
+  poll: boolean | number;
 };
 
 export type ServeCLIOptions = HostPortCLIOptions & {

packages/docusaurus/bin/docusaurus.js

@@ -146,8 +146,8 @@ cli
   )
   .option('--no-open', 'Do not open page in the browser (default: false)')
   .option(
-    '--poll',
+    '--poll [interval]',
-    'Use polling rather than watching for reload (default: false)',
+    'Use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds.',
   )
   .action((siteDir = '.', {port, host, hotOnly, open, poll}) => {
     wrapCommand(start)(path.resolve(siteDir), {

packages/docusaurus/src/commands/start.ts

@@ -81,10 +81,16 @@ export default async function start(
         .filter(Boolean),
     )
     .map(normalizeToSiteDir);
+
   const fsWatcher = chokidar.watch([...pluginPaths, CONFIG_FILE_NAME], {
     cwd: siteDir,
     ignoreInitial: true,
+    usePolling: !!cliOptions.poll,
+    interval: Number.isInteger(cliOptions.poll)
+      ? (cliOptions.poll as number)
+      : undefined,
   });
+
   ['add', 'change', 'unlink', 'addDir', 'unlinkDir'].forEach((event) =>
     fsWatcher.on(event, reload),
   );

packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap

@@ -6,7 +6,7 @@ exports[`loadConfig website with incomplete siteConfig 1`] = `
 "
 `;
 
-exports[`loadConfig website with no siteConfig 1`] = `"docusaurus.config.js not found"`;
+exports[`loadConfig website with no siteConfig 1`] = `"docusaurus.config.js not found at packages/docusaurus/src/server/__tests__/__fixtures__/nonExisting/docusaurus.config.js"`;
 
 exports[`loadConfig website with useless field (wrong field) in siteConfig 1`] = `
 "\\"favicon\\" is required

packages/docusaurus/src/server/config.ts

@@ -20,7 +20,12 @@ export default function loadConfig(siteDir: string): DocusaurusConfig {
   const configPath = path.resolve(siteDir, loadedConfigFileName);
 
   if (!fs.existsSync(configPath)) {
-    throw new Error(`${CONFIG_FILE_NAME} not found`);
+    throw new Error(
+      `${CONFIG_FILE_NAME} not found at ${path.relative(
+        process.cwd(),
+        configPath,
+      )}`,
+    );
   }
 
   const loadedConfig = importFresh(configPath) as Partial<DocusaurusConfig>;

website/docs/cli.md

@@ -49,7 +49,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https
 | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
 | `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
 | `--no-open` | `false` | Do not open automatically the page in the browser. |
-| `--poll` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
+| `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
 
 :::important