Changes to docusaurus.config.js only picked up once per yarn start invocation

[wpyoga]

🐛 Bug Report

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io I tried but cannot reproduce this issue on the sandbox
• I have read the console error message carefully

Description

When I run yarn start, and then edit & save docusaurus.config.js a few times, only the first save is recognized. If I want further changes to take effect, I have to terminate the development server (Ctrl-C) and run yarn start again.

Have you read the Contributing Guidelines on issues?

Yes

Steps to reproduce

Follow the steps here: https://docusaurus.io/docs/installation to create a new repo, then modify docusaurus.config.js.

1. Create a new docusaurus site:

   $ rm -rf test-01
   $ npx @docusaurus/init@latest init test-01 classic
   [...]
   We recommend that you begin by typing:
   
     cd test-01
     yarn start
   
   Happy building awesome websites!
   $ cd test-01

2. Run the development server:

   $ yarn start
   yarn run v1.22.10
   $ docusaurus start
   Starting the development server...
   Docusaurus website is running at "http://localhost:3000/".
   [...]
   ✔ Client
     Compiled successfully in 11.96s
   
   ℹ ｢wds｣: Project is running at http://localhost:3000/
   ℹ ｢wds｣: webpack output is served from /
   ℹ ｢wds｣: Content not from webpack is served from /home/william/Documents/wpyoga/test-docusaurus/test-01
   ℹ ｢wds｣: 404s will fallback to /index.html

3. Now change the first line in docusaurus.config.js and save:

   const lightCodeTheme = require('prism-react-renderer/themes/duotoneLight');

4. On the terminal, observe that the site is rebuilt:

   ✔ Client
     Compiled successfully in 362.65ms

5. Open http://localhost:3000/docs/intro and see that the code block theme has now changed.

6. Now change the first line in docusaurus.config.js again and save:

   const lightCodeTheme = require('prism-react-renderer/themes/vsLight');

7. On the terminal, there is no activity at all.

8. Reload the page at http://localhost:3000/docs/intro and see that the theme has not changed.

Further changes to docusaurus.config.js are not picked up until I stop the development server and start it again.

Expected behavior

When I modify docusaurus.config.js, the site is rebuilt.

Actual behavior

The expected behavior happens only the first time I modify docusaurus.config.js. Any further modifications to that file don't trigger site rebuild. In this state, modifications to documents inside blog/ and docs/ still trigger site rebuild.

Your environment

• Public source code: (I'm using the default site with classic preset)
• Public site URL: (not deployed yet)
• Docusaurus version used: 2.0.0-beta.4
• Environment name and version: Google Chrome 91.0.4472.114 (Official Build) (64-bit), Node.js 12.22.1, yarn 1.22.10
• Operating system and version: Linux Mint 20.2, based on Ubuntu 20.04.2 LTS

Additional info: I have also reproduced this bug using Node.js 14.17.4 and yarn 1.22.11.

Reproducible demo

Please follow the above steps to reproduce the issue.

[slorber]

Is it a problem that only happens with beta.4? Did it use to work with older versions?

Have you tried changing something else than the prism theme? Like navbar items or a md doc?

It is likely an issue in the file-watching system. It may be a problem on your system, or one of the libs we use, because it generally works fine for most users an we didn't change anything about that recently.

I suggest trying yarn start --poll 100 as a workaround

[wpyoga]

Hi @slorber thank you for your reply :)

Is it a problem that only happens with beta.4? Did it use to work with older versions?

I don't remember...

However, I tried creating a new site using docusaurus 2.0.0-beta.0, the same problem persists.

Have you tried changing something else than the prism theme? Like navbar items or a md doc?

I tried changing the navbar title, it exhibits the same behaviour.

However, if I change an MD document, the site is rebuilt.

It is likely an issue in the file-watching system. It may be a problem on your system, or one of the libs we use, because it generally works fine for most users an we didn't change anything about that recently.

Okay... is there a difference in the file-watching system, for docusaurus.config.js and for markdown documents inside blog/ and docs/? I'm asking because the behavior seems different. markdown documents inside docs/ and blog/, when they are edited or even touch-ed, will trigger a site rebuild.

I suggest trying yarn start --poll 100 as a workaround

Using this, the site will usually be rebuilt after I change some value in docusaurus.config.js.

[wpyoga]

docusaurus 2.0.0-beta.0 and 2.0.0-beta.4 have the same behavior:

action	yarn start	yarn start --poll 100
touch docusaurus.config.js	✗	✗
sed -i docusaurus.config.js -e "s/title: 'My Site.*/title: 'My Site $RANDOM',/"	✓ (ONLY THE FIRST TIME)	✓
touch docs	✗	✗
touch docs/intro.md	✓	✓
touch blog	✗	✗
touch blog/2019-05-28-hola.md	✓	✓

[slorber]

Thanks

Okay... is there a difference in the file-watching system, for docusaurus.config.js and for markdown documents inside blog/ and docs/? I'm asking because the behavior seems different. markdown documents inside docs/ and blog/, when they are edited or even touch-ed, will trigger a site rebuild.

Yes, docs are watched by Webpack's internal dependency graph system, while the config file and other things are watched using the chokidar lib.

https://github.com/facebook/docusaurus/blob/master/packages/docusaurus/src/commands/start.ts#L115

  const fsWatcher = chokidar.watch(pathsToWatch, {
    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),
  );

If you want to help us debug this issue, you can try to add some logs in node_modules/@docusaurus/lib/commands/start.js and see if some file-system events are not triggered, or try different chokidar options?

Maybe you are using symlinks or a special file-system folder, or you have some specific file-system that is not supported by chokidar, or chokidar might have a bug preventing you to get the watcher events being fired.

Unfortunately, it will be hard for me to solve this issue. It's also not very probable that this is a Docusaurus bug so I'm going to closes it, but happy to re-open if you can prove that chokidar is working correctly and this is our Docusaurus integration that fails. Otherrwise I suggest creating a small repro and opening a bug report on Chokidar directly

[wpyoga]

Hi @slorber , thanks for suggesting that! I went down the rabbit hole, and I think I re-discovered paulmillr/chokidar#791 and its related issues, including paulmillr/chokidar#35, paulmillr/chokidar#601, and paulmillr/chokidar#742

I've set up a repo to easily reproduce this problem at: https://github.com/wpyoga/repro-docusaurus-5252 . It contains both docusaurus and non-docusaurus-specific (chokidar only) code. You are welcome to take a look and try it out. So far it works on my Linux laptop.

I'm using the standard ext4 file system. And I'm not using symlinks either.

docs are watched by Webpack's internal dependency graph system

Since the docs seem to be watched quite reliably, is it possible to watch the config file using a similar mechanism?

[slorber]

Thanks for investigating this.

What I understand is that it's an issue happening only when using some editors like Vim right?

Unfortunately, I'm not sure what I can do here, hopefully Chokidar will fix this.

Since the docs seem to be watched quite reliably, is it possible to watch the config file using a similar mechanism?

I'm not sure it is possible, and not even sure the Webpack watcher system is public api. Webpack is responsible for tracking the dependency graph of the frontend React application to build, not the NodeJS code. We use Chokidar to watch for changes in the Node.js side, which Webpack is not responsible for.