facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.03k stars 8.41k forks source link

Hot reloading doesn't work when using `module.exports` for `docusaurus.config.js` and/or `sidebars.js` #9698

Open farlowdw opened 9 months ago

farlowdw commented 9 months ago

Have you read the Contributing Guidelines on issues?

Prerequisites

Description

Hot reloading for docusaurus.config.js ceases to work if it uses module.exports:

module.exports = async function createConfigAsync() {
  return {
    ...
  };
};

Changes to this document are not reflected (even something minor like a change to the title string) unless the project is rebuilt. This issue does not occur if module.exports is not used:

/** @type {import('@docusaurus/types').Config} */
const config = {
  ...
};

export default config;

Similarly, hot reloading for sidebars.js ceases to work if module.exports is used:

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  docs: ['intro', 'intro-other'],
};

module.exports = sidebars;

This problem goes away once module.exports is not used:

const sidebars = {
  docs: ['intro', 'intro-other'],
};

export default sidebars;

There's a small section in the migration guide for migrating from v2 to v3 that mentions the new internal config loading library was changed from import-fresh to jiti. Specifically, the migration guide mentions the library is responsible for loading files such as docusaurus.config.js, sidebars.js, and Docusaurus plugins:

In theory, you have nothing to do, and your existing config files should keep working as before. However, this is a major dependency swap and subtle behavior changes could occur.

The subtle problematic behavior outlined in this issue seems to be due to this major dependency swap (I never encountered this problematic behavior with my v2 sites).

Reproducible demo

https://stackblitz.com/edit/github-cvjzww-1ay5tg?file=docusaurus.config.js

Steps to reproduce

Visit the link to the example repo and try making changes to either the docusaurus.config.js or sidebars.js files as they currently exist (i.e., with module.exports). The changes will not register and hot reloading will fail. It's as if these files are not being watched anymore.

Expected behavior

Simple changes to the docusaurus.config.js file should be reflected via hot reloading (and they are when not using module.exports):

gif-3

Similarly, changes to sidebars.js should be reflected via hot reloading (and they also are when not using module.exports):

gif-4

Actual behavior

Simple changes to docusaurus.config.js do not register and hot reloading fails when module.exports is present:

gif-1

The same problem applies to sidebars.js:

gif-2

Your environment

See example repo link for complete environment.

Self-service

gagdiez commented 9 months ago

I can confirm this bug, and that the solution of changing modules.exports to export default fixes it