Upgrade to DS beta.21 breaks SSR builds with useDocsVersion error

[markerikson]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

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 have read the console error message carefully (if applicable).

Description

I just tried upgrading Redux Toolkit's website from beta.7 to beta.21, and I'm seeing a variation on the "can't find chalk" error that was discussed in #7398:

TypeError: source_default(...).bold is not a function
TypeError: source_default(...).bold is not a function
TypeError: source_default(...).bold is not a function
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
    at D:\Projects\redux\redux-toolkit\node_modules\@docusaurus\core\lib\webpack\utils.js:180:24

fter going into serverEntry.js inside of node_modules, and commenting out every use of chalk in the error handling, and adding an additional console.error('Actual error: ', err) statement, I'm finally getting something meaningful:

[ERROR] Docusaurus server-side rendering could not render static page with path /rtk-query/usage/error-handling.
Actual error:  ReactContextError
    at useDocsVersion (main:9127:99)
    at DocVersionBanner (main:9136:814)
    at zb (main:81525:195)
    at Cb (main:81528:254)
    at W (main:81534:89)
    at Db (main:81537:98)
    at Eb (main:81536:122)
    at W (main:81534:345)
    at Db (main:81537:98)
    at Cb (main:81529:131) {
  message: 'Hook useDocsVersion is called outside the <DocsVersionProvider>. '
}

except that seems to be internal to Docusaurus and I have no idea why that provider doesn't exist.

so, three problems here:

• The actual error isn't being printed at all
• The chalk usages appear to be broken
• I'm getting this useDocsVersion error just from upgrading DS

I'm seeing the same build failures both locally and in CI.

FWIW, I was just able to upgrade the Redux core docs from beta.18 to beta.21 with no errors, so maybe it has to do with RTK's Yarn monorepo?

Reproducible demo

reduxjs/redux-toolkit#2458

Steps to reproduce

1. Clone the Redux Toolkit repo as of branch https://github.com/reduxjs/redux-toolkit/tree/docs/ds2-21-updates , as shown in Update Docusaurus to 2.b21 reduxjs/redux-toolkit#2458
2. Run yarn at the root to install
3. cd website
4. yarn build

Expected behavior

The build would succeed cleanly, with no errors

Actual behavior

Per the description, and after adding additional logging to node_modules/@docusaurus/core/lib/client/serverEntry.js, the actual error appears to be

[ERROR] Docusaurus server-side rendering could not render static page with path /rtk-query/usage/error-handling.
Actual error:  ReactContextError
    at useDocsVersion (main:9127:99)
    at DocVersionBanner (main:9136:814)
    at zb (main:81525:195)
    at Cb (main:81528:254)
    at W (main:81534:89)
    at Db (main:81537:98)
    at Eb (main:81536:122)
    at W (main:81534:345)
    at Db (main:81537:98)
    at Cb (main:81529:131) {
  message: 'Hook useDocsVersion is called outside the <DocsVersionProvider>. '
}

So, somehow useDocsVersion isn't finding a provider after the upgrade.

Your environment

• Public source code: https://github.com/reduxjs/redux-toolkit/tree/docs/ds2-21-updates/website
• Public site URL: https://redux-toolkit.js.org
• Docusaurus version used: 2.0-beta.21
• Environment/OS: Windows 11, Node 1; also GH Actions CI

Self-service

• I'd be willing to fix this bug myself.

[slorber]

@markerikson you have a custom DocPage component:

docLayoutComponent: '../src/theme/DocPageWithBraveWarning',

Our new entrypoint now provides multiple providers so that all subcomponents can access docs/version data easily with hooks anywhere (ie no props needed anymore):

<DocsVersionProvider version={versionMetadata}>
  <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
    <DocPageLayout>{docElement}</DocPageLayout>
  </DocsSidebarProvider>
</DocsVersionProvider>

Instead of providing a custom config entry point for that page (that you now have to maintain yourself over time, ensuring it remains compatible with Docusaurus), you can try to swizzle components instead.

---

Looks like @msutkowski added a Brave warning to Docusaurus documents: reduxjs/redux-toolkit@599d4b8#diff-eaeffea00bcc3667ab8ddf261520fc47589a396fb6eb14afd916f40b98e4d682

Not 100% sure but it looks like we can summarize this customization as:

<div>
  <BraveWarning />
  <MDXProvider components={MDXComponents}>{children}</MDXProvider>
</div>

This is a lot of copied code for such small customization.

We have split the DocPage component into much smaller parts to make these kinds of customizations much easier: you would swizzle a much smaller component instead. That remains a burden on your side to maintain, but a much smaller one, less likely to break on upgrades.

For example, solutions you can try:

Swizzle eject @theme/DocItem/Content:

yarn swizzle @docusaurus/theme-classic DocItem/Content --eject --typescript --danger

export default function DocItemContent({children}: Props): JSX.Element {
  const syntheticTitle = useSyntheticTitle();
  return (
    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
      {syntheticTitle && (
        <header>
          <Heading as="h1">{syntheticTitle}</Heading>
        </header>
      )}
      <BraveWarning />
      <MDXContent>{children}</MDXContent>
    </div>
  );
}

Note: If the warning should also be displayed in MDX blog posts and MDX pages, you can also eject MDXContent, this component directly wraps any MDX content before rendering it.

Swizzle wrap @theme/DocItem/Content:

yarn swizzle @docusaurus/theme-classic DocItem/Content --wrap --typescript --danger

export default function ContentWrapper(props: Props): JSX.Element {
  return (
    <Content {...props}>
      <BraveWarning />
      {props.children}
    </Content>
  );
}

---

Both solutions works. We usually prefer to wrap as it is less likely to break on an upgrade.

Note these components are still marked as "unsafe" to swizzle (require the --danger CLI flag) because we are not ready to commit to SemVer retro compatibility on those.

In any case: it is still better than ejecting the DocPage component like you previously did: it is much larger/complex and we don't provide SemVer compatibility on it either 😅 Like we have seen here: it broke on an upgrade due to internal changes.

Does it make sense to you?

[slorber]

Regarding the chalk errors, not sure what is happening 🤷‍♂️

Per the description, and after adding additional logging to node_modules/@docusaurus/core/lib/client/serverEntry.js, the actual error appears to be

What did you change here?

[Josh-Cena]

The chalk errors happen when SSR throws an error and tries to log a message. To this day I don’t know exactly how that happens. Usually re-installing fixes it.

[pranabdas]

In case it gives any additional hint: probably I see related issue with the latest canary version in one of my projects which uses @easyops-cn/docusaurus-search-local. When I try to build site:

[ERROR] Docusaurus server-side rendering could not render static page with path /404.html.
[ERROR] Docusaurus server-side rendering could not render static page with path /search.
[ERROR] Docusaurus server-side rendering could not render static page with path /.
[ERROR] Docusaurus server-side rendering could not render static page with path /xxxx.
// ... Snipped: multiple such lines

ReactContextError
ReactContextError
ReactContextError
// ... Snipped: multiple such lines
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
    at /workspaces/xxxxl/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
    at /workspaces/xxxx/node_modules/webpack/lib/MultiCompiler.js:554:14
    at processQueueWorker (/workspaces/xxxx/node_modules/webpack/lib/MultiCompiler.js:491:6)
    at processTicksAndRejections (node:internal/process/task_queues:78:11)

When I try to serve:

In the browser console:

Steps to reproduce:

1. Create a brand new Docusaurus site:

npx create-docusaurus@latest my-website classic

2. Install @easyops-cn/docusaurus-search-local:

cd my-website
npm install --save @easyops-cn/docusaurus-search-local

3. Include following in docusaurus.config.js:

  themes: [
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      {
        hashed: true,
      },
    ],
  ],

4. Install latest canary:

npm i --save-exact @docusaurus/core@canary @docusaurus/preset-classic@canary

5. Try to serve or build.

npm start
npm run build

[markerikson]

FWIW we were able to fix RTK's docs build by following the advice here. This can probably be closed.

[Josh-Cena]

@pranabdas Your error is because you are using a different version of @docusaurus/theme-common from what the search plugin is using, which causes the context provider and consumer to read from different contexts. It's unrelated. If you are using an external plugin that does not declare peer dependency on theme-common (and tolerate canary versions), you'll very likely not be able to use canary.

@markerikson Great to know—let's close this then.

[slorber]

@pranabdas I can reproduce your problem and it doesn't seem like there are 2 different versions of @docusaurus/theme-common

This is not related to the current issue, so let's discuss it in another place.

Looks like the search plugin introduced changes that makes it break on canary
Not sure why exactly that fails but will report on the PR there: easyops-cn/docusaurus-search-local#205

[slorber]

@pranabdas see #7728

[ianobermiller]

For anyone who ended up here with TypeError: source_default(...).bold is not a function and wants to see what the actual underlying error is:

• open node_modules/@docusaurus/core/lib/client/serverEntry.js
• Find the line with Docusaurus server-side rendering could not render static page with path
• Remove all references to chalk

E.g. before:

console.error(chalk.red(`${chalk.bold('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${chalk.cyan.underline(locals.path)}.`));

after:

console.error((`${('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${(locals.path)}.`));

In my case it was Error: Minified React error #31; and pointed me to the failing path.

[Addono]

Continuing on the answer from @ianobermiller: Removing all references to chalk can be done by doing a regex-replace in node_modules/@docusaurus/core/lib/client/serverEntry.js in VS Code.

Just let it search for the following RegEx and replace it all with the empty string and you're good to go:

chalk\.[\w\.]+