@docusaurus/core 2.4.1 → 3.0.0-beta.0

package/bin/beforeCli.mjs

@@ -10,6 +10,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import {createRequire} from 'module';
+import shell from 'shelljs';
 import logger from '@docusaurus/logger';
 import semver from 'semver';
 import updateNotifier from 'update-notifier';
@@ -105,18 +106,33 @@ export default async function beforeCli() {
       .map((p) => p.concat('@latest'))
       .join(' ');
 
+    const getYarnVersion = async () => {
+      if (!(await fs.pathExists(path.resolve('yarn.lock')))) {
+        return undefined;
+      }
+
+      const yarnVersionResult = shell.exec('yarn --version', {silent: true});
+      if (yarnVersionResult?.code === 0) {
+        const majorVersion = parseInt(
+          yarnVersionResult.stdout?.trim().split('.')[0] ?? '',
+          10,
+        );
+        if (!Number.isNaN(majorVersion)) {
+          return majorVersion;
+        }
+      }
+
+      return undefined;
+    };
+
     const getUpgradeCommand = async () => {
-      const isYarnUsed = await fs.pathExists(path.resolve('yarn.lock'));
-      if (!isYarnUsed) {
+      const yarnVersion = await getYarnVersion();
+      if (!yarnVersion) {
         return `npm i ${siteDocusaurusPackagesForUpdate}`;
       }
-
-      const isYarnClassicUsed = !(await fs.pathExists(
-        path.resolve('.yarnrc.yml'),
-      ));
-      return isYarnClassicUsed
-        ? `yarn upgrade ${siteDocusaurusPackagesForUpdate}`
-        : `yarn up ${siteDocusaurusPackagesForUpdate}`;
+      return yarnVersion >= 2
+        ? `yarn up ${siteDocusaurusPackagesForUpdate}`
+        : `yarn upgrade ${siteDocusaurusPackagesForUpdate}`;
     };
 
     /** @type {import('boxen').Options} */
@@ -125,7 +141,16 @@ export default async function beforeCli() {
       margin: 1,
       align: 'center',
       borderColor: 'yellow',
-      borderStyle: 'round',
+      borderStyle: {
+        topLeft: ' ',
+        topRight: ' ',
+        bottomLeft: ' ',
+        bottomRight: ' ',
+        top: '-',
+        bottom: '-',
+        left: ' ',
+        right: ' ',
+      },
     };
 
     const docusaurusUpdateMessage = boxen(

package/bin/docusaurus.mjs

@@ -37,6 +37,10 @@ cli.version(DOCUSAURUS_VERSION).usage('<command> [options]');
 cli
   .command('build [siteDir]')
   .description('Build website.')
+  .option(
+    '--dev',
+    'Builds the website in dev mode, including full React error messages.',
+  )
   .option(
     '--bundle-analyzer',
     'visualize size of webpack output files with an interactive zoomable tree map (default: false)',
@@ -244,7 +248,11 @@ if (!process.argv.slice(2).length) {
 cli.parse(process.argv);
 
 process.on('unhandledRejection', (err) => {
-  logger.error(err instanceof Error ? err.stack : err);
+  console.log('');
+  // Do not use logger.error here: it does not print error causes
+  console.error(err);
+  console.log('');
+
   logger.info`Docusaurus version: number=${DOCUSAURUS_VERSION}
 Node version: number=${process.version}`;
   process.exit(1);

package/lib/babel/preset.js

@@ -36,7 +36,12 @@ function getTransformOptions(isServer) {
                         exclude: ['transform-typeof-symbol'],
                     },
                 ],
-            require.resolve('@babel/preset-react'),
+            [
+                require.resolve('@babel/preset-react'),
+                {
+                    runtime: 'automatic',
+                },
+            ],
             require.resolve('@babel/preset-typescript'),
         ],
         plugins: [

package/lib/client/App.js

@@ -20,6 +20,7 @@ import SiteMetadataDefaults from './SiteMetadataDefaults';
 // TODO, quick fix for CSS insertion order
 // eslint-disable-next-line import/order
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import HasHydratedDataAttribute from './hasHydratedDataAttribute';
 export default function App() {
     const routeElement = renderRoutes(routes);
     const location = useLocation();
@@ -34,6 +35,7 @@ export default function App() {
               {routeElement}
             </PendingNavigation>
           </Root>
+          <HasHydratedDataAttribute />
         </BrowserContextProvider>
       </DocusaurusContextProvider>
     </ErrorBoundary>);

package/lib/client/BaseUrlIssueBanner/index.d.ts

@@ -6,12 +6,6 @@
  */
 /// <reference types="react" />
 import './styles.module.css';
-declare const InsertBannerWindowAttribute = "__DOCUSAURUS_INSERT_BASEURL_BANNER";
-declare global {
-    interface Window {
-        [InsertBannerWindowAttribute]: boolean;
-    }
-}
 /**
  * We want to help the users with a bad baseUrl configuration (very common
  * error). Help message is inlined, and hidden if JS or CSS is able to load.
@@ -24,4 +18,3 @@ declare global {
  * @see https://github.com/facebook/docusaurus/pull/3621
  */
 export default function MaybeBaseUrlIssueBanner(): JSX.Element | null;
-export {};

package/lib/client/BaseUrlIssueBanner/index.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { useLayoutEffect } from 'react';
+import React from 'react';
 import { useLocation } from '@docusaurus/router';
 import Head from '@docusaurus/Head';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
@@ -16,7 +16,6 @@ import './styles.module.css';
 const BannerContainerId = '__docusaurus-base-url-issue-banner-container';
 const BannerId = '__docusaurus-base-url-issue-banner';
 const SuggestionContainerId = '__docusaurus-base-url-issue-banner-suggestion-container';
-const InsertBannerWindowAttribute = '__DOCUSAURUS_INSERT_BASEURL_BANNER';
 // It is important to not use React to render this banner
 // otherwise Google would index it, even if it's hidden with some critical CSS!
 // See https://github.com/facebook/docusaurus/issues/4028
@@ -36,24 +35,19 @@ function createInlineHtmlBanner(baseUrl) {
 function createInlineScript(baseUrl) {
     /* language=js */
     return `
-window['${InsertBannerWindowAttribute}'] = true;
-
-document.addEventListener('DOMContentLoaded', maybeInsertBanner);
-
-function maybeInsertBanner() {
-  var shouldInsert = window['${InsertBannerWindowAttribute}'];
+document.addEventListener('DOMContentLoaded', function maybeInsertBanner() {
+  var shouldInsert = typeof window['docusaurus'] === 'undefined';
   shouldInsert && insertBanner();
-}
+});
 
 function insertBanner() {
-  var bannerContainer = document.getElementById('${BannerContainerId}');
-  if (!bannerContainer) {
-    return;
-  }
+  var bannerContainer = document.createElement('div');
+  bannerContainer.id = '${BannerContainerId}';
   var bannerHtml = ${JSON.stringify(createInlineHtmlBanner(baseUrl))
         // See https://redux.js.org/recipes/server-rendering/#security-considerations
         .replace(/</g, '\\\u003c')};
   bannerContainer.innerHTML = bannerHtml;
+  document.body.prepend(bannerContainer);
   var suggestionContainer = document.getElementById('${SuggestionContainerId}');
   var actualHomePagePath = window.location.pathname;
   var suggestedBaseUrl = actualHomePagePath.substr(-1) === '/'
@@ -65,11 +59,6 @@ function insertBanner() {
 }
 function BaseUrlIssueBanner() {
     const { siteConfig: { baseUrl }, } = useDocusaurusContext();
-    // useLayoutEffect fires before DOMContentLoaded.
-    // It gives the opportunity to avoid inserting the banner in the first place
-    useLayoutEffect(() => {
-        window[InsertBannerWindowAttribute] = false;
-    }, []);
     return (<>
       {!ExecutionEnvironment.canUseDOM && (
         // Safe to use `ExecutionEnvironment`, because `Head` is purely
@@ -77,7 +66,6 @@ function BaseUrlIssueBanner() {
         <Head>
           <script>{createInlineScript(baseUrl)}</script>
         </Head>)}
-      <div id={BannerContainerId}/>
     </>);
 }
 /**

package/lib/client/ClientLifecyclesDispatcher.js

@@ -4,8 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { useLayoutEffect } from 'react';
 import clientModules from '@generated/client-modules';
+import useIsomorphicLayoutEffect from './exports/useIsomorphicLayoutEffect';
 export function dispatchLifecycleAction(lifecycleAction, ...args) {
     const callbacks = clientModules.map((clientModule) => {
         const lifecycleFunction = (clientModule.default?.[lifecycleAction] ??
@@ -36,7 +36,7 @@ function scrollAfterNavigation({ location, previousLocation, }) {
     }
 }
 function ClientLifecyclesDispatcher({ children, location, previousLocation, }) {
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
         if (previousLocation !== location) {
             scrollAfterNavigation({ location, previousLocation });
             dispatchLifecycleAction('onRouteDidUpdate', { previousLocation, location });

package/lib/client/LinksCollector.d.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { type ReactNode } from 'react';
-declare type LinksCollector = {
+type LinksCollector = {
     collectLink: (link: string) => void;
 };
-declare type StatefulLinksCollector = LinksCollector & {
+type StatefulLinksCollector = LinksCollector & {
     getCollectedLinks: () => string[];
 };
 export declare const createStatefulLinksCollector: () => StatefulLinksCollector;

package/lib/client/PendingNavigation.d.ts

@@ -6,11 +6,11 @@
  */
 import React from 'react';
 import type { Location } from 'history';
-declare type Props = {
+type Props = {
     readonly location: Location;
     readonly children: JSX.Element;
 };
-declare type State = {
+type State = {
     nextRouteHasLoaded: boolean;
 };
 declare class PendingNavigation extends React.Component<Props, State> {

package/lib/client/clientEntry.js

@@ -5,29 +5,43 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import ReactDOM from 'react-dom';
+import ReactDOM from 'react-dom/client';
 import { BrowserRouter } from 'react-router-dom';
 import { HelmetProvider } from 'react-helmet-async';
 import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import App from './App';
 import preload from './preload';
 import docusaurus from './docusaurus';
+const hydrate = Boolean(process.env.HYDRATE_CLIENT_ENTRY);
 // Client-side render (e.g: running in browser) to become single-page
 // application (SPA).
 if (ExecutionEnvironment.canUseDOM) {
     window.docusaurus = docusaurus;
-    // For production, attempt to hydrate existing markup for performant
-    // first-load experience.
-    // For development, there is no existing markup so we had to render it.
-    // We also preload async component to avoid first-load loading screen.
-    const renderMethod = process.env.NODE_ENV === 'production' ? ReactDOM.hydrate : ReactDOM.render;
-    preload(window.location.pathname).then(() => {
-        renderMethod(<HelmetProvider>
-        <BrowserRouter>
-          <App />
-        </BrowserRouter>
-      </HelmetProvider>, document.getElementById('__docusaurus'));
-    });
+    const container = document.getElementById('__docusaurus');
+    const app = (<HelmetProvider>
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </HelmetProvider>);
+    const onRecoverableError = (error) => {
+        console.error('Docusaurus React Root onRecoverableError:', error);
+    };
+    const renderApp = () => {
+        if (hydrate) {
+            React.startTransition(() => {
+                ReactDOM.hydrateRoot(container, app, {
+                    onRecoverableError,
+                });
+            });
+        }
+        else {
+            const root = ReactDOM.createRoot(container, { onRecoverableError });
+            React.startTransition(() => {
+                root.render(app);
+            });
+        }
+    };
+    preload(window.location.pathname).then(renderApp);
     // Webpack Hot Module Replacement API
     if (module.hot) {
         // Self-accepting method/ trick

package/lib/client/exports/ErrorBoundary.d.ts

@@ -7,7 +7,7 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 import React, { type ReactNode } from 'react';
 import type { Props } from '@docusaurus/ErrorBoundary';
-declare type State = {
+type State = {
     error: Error | null;
 };
 export default class ErrorBoundary extends React.Component<Props, State> {

package/lib/client/exports/Link.d.ts

@@ -7,5 +7,5 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 import React from 'react';
 import type { Props } from '@docusaurus/Link';
-declare const _default: React.ForwardRefExoticComponent<Pick<Props, "location" | "children" | "replace" | "slot" | "style" | "title" | "component" | "exact" | "sensitive" | "strict" | "type" | "key" | "id" | "lang" | "dir" | "property" | "rel" | "href" | "isNavLink" | "className" | "to" | "innerRef" | "download" | "hrefLang" | "media" | "ping" | "target" | "referrerPolicy" | "defaultChecked" | "defaultValue" | "suppressContentEditableWarning" | "suppressHydrationWarning" | "accessKey" | "contentEditable" | "contextMenu" | "draggable" | "hidden" | "placeholder" | "spellCheck" | "tabIndex" | "translate" | "radioGroup" | "role" | "about" | "datatype" | "inlist" | "prefix" | "resource" | "typeof" | "vocab" | "autoCapitalize" | "autoCorrect" | "autoSave" | "color" | "itemProp" | "itemScope" | "itemType" | "itemID" | "itemRef" | "results" | "security" | "unselectable" | "inputMode" | "is" | "aria-activedescendant" | "aria-atomic" | "aria-autocomplete" | "aria-busy" | "aria-checked" | "aria-colcount" | "aria-colindex" | "aria-colspan" | "aria-controls" | "aria-current" | "aria-describedby" | "aria-details" | "aria-disabled" | "aria-dropeffect" | "aria-errormessage" | "aria-expanded" | "aria-flowto" | "aria-grabbed" | "aria-haspopup" | "aria-hidden" | "aria-invalid" | "aria-keyshortcuts" | "aria-label" | "aria-labelledby" | "aria-level" | "aria-live" | "aria-modal" | "aria-multiline" | "aria-multiselectable" | "aria-orientation" | "aria-owns" | "aria-placeholder" | "aria-posinset" | "aria-pressed" | "aria-readonly" | "aria-relevant" | "aria-required" | "aria-roledescription" | "aria-rowcount" | "aria-rowindex" | "aria-rowspan" | "aria-selected" | "aria-setsize" | "aria-sort" | "aria-valuemax" | "aria-valuemin" | "aria-valuenow" | "aria-valuetext" | "dangerouslySetInnerHTML" | "onCopy" | "onCopyCapture" | "onCut" | "onCutCapture" | "onPaste" | "onPasteCapture" | "onCompositionEnd" | "onCompositionEndCapture" | "onCompositionStart" | "onCompositionStartCapture" | "onCompositionUpdate" | "onCompositionUpdateCapture" | "onFocus" | "onFocusCapture" | "onBlur" | "onBlurCapture" | "onChange" | "onChangeCapture" | "onBeforeInput" | "onBeforeInputCapture" | "onInput" | "onInputCapture" | "onReset" | "onResetCapture" | "onSubmit" | "onSubmitCapture" | "onInvalid" | "onInvalidCapture" | "onLoad" | "onLoadCapture" | "onError" | "onErrorCapture" | "onKeyDown" | "onKeyDownCapture" | "onKeyPress" | "onKeyPressCapture" | "onKeyUp" | "onKeyUpCapture" | "onAbort" | "onAbortCapture" | "onCanPlay" | "onCanPlayCapture" | "onCanPlayThrough" | "onCanPlayThroughCapture" | "onDurationChange" | "onDurationChangeCapture" | "onEmptied" | "onEmptiedCapture" | "onEncrypted" | "onEncryptedCapture" | "onEnded" | "onEndedCapture" | "onLoadedData" | "onLoadedDataCapture" | "onLoadedMetadata" | "onLoadedMetadataCapture" | "onLoadStart" | "onLoadStartCapture" | "onPause" | "onPauseCapture" | "onPlay" | "onPlayCapture" | "onPlaying" | "onPlayingCapture" | "onProgress" | "onProgressCapture" | "onRateChange" | "onRateChangeCapture" | "onSeeked" | "onSeekedCapture" | "onSeeking" | "onSeekingCapture" | "onStalled" | "onStalledCapture" | "onSuspend" | "onSuspendCapture" | "onTimeUpdate" | "onTimeUpdateCapture" | "onVolumeChange" | "onVolumeChangeCapture" | "onWaiting" | "onWaitingCapture" | "onAuxClick" | "onAuxClickCapture" | "onClick" | "onClickCapture" | "onContextMenu" | "onContextMenuCapture" | "onDoubleClick" | "onDoubleClickCapture" | "onDrag" | "onDragCapture" | "onDragEnd" | "onDragEndCapture" | "onDragEnter" | "onDragEnterCapture" | "onDragExit" | "onDragExitCapture" | "onDragLeave" | "onDragLeaveCapture" | "onDragOver" | "onDragOverCapture" | "onDragStart" | "onDragStartCapture" | "onDrop" | "onDropCapture" | "onMouseDown" | "onMouseDownCapture" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "onMouseMoveCapture" | "onMouseOut" | "onMouseOutCapture" | "onMouseOver" | "onMouseOverCapture" | "onMouseUp" | "onMouseUpCapture" | "onSelect" | "onSelectCapture" | "onTouchCancel" | "onTouchCancelCapture" | "onTouchEnd" | "onTouchEndCapture" | "onTouchMove" | "onTouchMoveCapture" | "onTouchStart" | "onTouchStartCapture" | "onPointerDown" | "onPointerDownCapture" | "onPointerMove" | "onPointerMoveCapture" | "onPointerUp" | "onPointerUpCapture" | "onPointerCancel" | "onPointerCancelCapture" | "onPointerEnter" | "onPointerEnterCapture" | "onPointerLeave" | "onPointerLeaveCapture" | "onPointerOver" | "onPointerOverCapture" | "onPointerOut" | "onPointerOutCapture" | "onGotPointerCapture" | "onGotPointerCaptureCapture" | "onLostPointerCapture" | "onLostPointerCaptureCapture" | "onScroll" | "onScrollCapture" | "onWheel" | "onWheelCapture" | "onAnimationStart" | "onAnimationStartCapture" | "onAnimationEnd" | "onAnimationEndCapture" | "onAnimationIteration" | "onAnimationIterationCapture" | "onTransitionEnd" | "onTransitionEndCapture" | "activeClassName" | "activeStyle" | "isActive" | "data-noBrokenLinkCheck" | "autoAddBaseUrl"> & React.RefAttributes<HTMLAnchorElement>>;
+declare const _default: React.ForwardRefExoticComponent<Omit<Props, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
 export default _default;

package/lib/client/exports/Link.js

@@ -103,7 +103,7 @@ function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLi
         linksCollector.collectLink(targetLink);
     }
     return isRegularHtmlLink ? (
-    // eslint-disable-next-line jsx-a11y/anchor-has-content
+    // eslint-disable-next-line jsx-a11y/anchor-has-content, @docusaurus/no-html-links
     <a ref={innerRef} href={targetLink} {...(targetLinkUnprefixed &&
         !isInternal && { target: '_blank', rel: 'noopener noreferrer' })} {...props}/>) : (<LinkComponent {...props} onMouseEnter={onInteractionEnter} onTouchStart={onInteractionEnter} innerRef={handleRef} to={targetLink} 
     // Avoid "React does not recognize the `activeClassName` prop on a DOM

package/lib/client/exports/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useEffect } from 'react';
+/**
+ * This hook is like `useLayoutEffect`, but without the SSR warning.
+ * It seems hacky but it's used in many React libs (Redux, Formik...).
+ * Also mentioned here: https://github.com/facebook/react/issues/16956
+ *
+ * It is useful when you need to update a ref as soon as possible after a React
+ * render (before `useEffect`).
+ *
+ * TODO should become unnecessary in React v19?
+ * https://github.com/facebook/react/pull/26395
+ * This was added in core with Docusaurus v3 but kept undocumented on purpose
+ */
+declare const useIsomorphicLayoutEffect: typeof useEffect;
+export default useIsomorphicLayoutEffect;

package/lib/client/exports/useIsomorphicLayoutEffect.js

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useEffect, useLayoutEffect } from 'react';
+import ExecutionEnvironment from './ExecutionEnvironment';
+/**
+ * This hook is like `useLayoutEffect`, but without the SSR warning.
+ * It seems hacky but it's used in many React libs (Redux, Formik...).
+ * Also mentioned here: https://github.com/facebook/react/issues/16956
+ *
+ * It is useful when you need to update a ref as soon as possible after a React
+ * render (before `useEffect`).
+ *
+ * TODO should become unnecessary in React v19?
+ * https://github.com/facebook/react/pull/26395
+ * This was added in core with Docusaurus v3 but kept undocumented on purpose
+ */
+const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
+    ? useLayoutEffect
+    : useEffect;
+export default useIsomorphicLayoutEffect;

package/lib/{webpack/plugins/LogPlugin.d.ts → client/hasHydratedDataAttribute.d.ts}

@@ -4,8 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import WebpackBar from 'webpackbar';
-import type { Compiler } from 'webpack';
-export default class LogPlugin extends WebpackBar {
-    apply(compiler: Compiler): void;
-}
+/// <reference types="react" />
+export default function HasHydratedDataAttribute(): JSX.Element;

package/lib/client/hasHydratedDataAttribute.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import Head from '@docusaurus/Head';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+// See https://github.com/facebook/docusaurus/pull/9256
+// Docusaurus adds a <html data-has-hydrated="true"> after hydration
+export default function HasHydratedDataAttribute() {
+    const isBrowser = useIsBrowser();
+    return (<Head>
+      <html data-has-hydrated={isBrowser}/>
+    </Head>);
+}

package/lib/client/serverEntry.js

@@ -9,14 +9,13 @@ import path from 'path';
 import fs from 'fs-extra';
 // eslint-disable-next-line no-restricted-imports
 import _ from 'lodash';
-import chalk from 'chalk';
 import * as eta from 'eta';
 import { StaticRouter } from 'react-router-dom';
-import ReactDOMServer from 'react-dom/server';
 import { HelmetProvider } from 'react-helmet-async';
 import { getBundles } from 'react-loadable-ssr-addon-v5-slorber';
 import Loadable from 'react-loadable';
 import { minify } from 'html-minifier-terser';
+import { renderStaticApp } from './serverRenderer';
 import preload from './preload';
 import App from './App';
 import { createStatefulLinksCollector, LinksCollectorProvider, } from './LinksCollector';
@@ -27,24 +26,31 @@ function renderSSRTemplate(ssrTemplate, data) {
     const compiled = getCompiledSSRTemplate(ssrTemplate);
     return compiled(data, eta.defaultConfig);
 }
+function buildSSRErrorMessage({ error, pathname, }) {
+    const parts = [
+        `Docusaurus server-side rendering could not render static page with path ${pathname} because of error: ${error.message}`,
+    ];
+    const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
+    if (isNotDefinedErrorRegex.test(error.message)) {
+        // prettier-ignore
+        parts.push(`It looks like you are using code that should run on the client-side only.
+To get around it, try using \`<BrowserOnly>\` (https://docusaurus.io/docs/docusaurus-core/#browseronly) or \`ExecutionEnvironment\` (https://docusaurus.io/docs/docusaurus-core/#executionenvironment).
+It might also require to wrap your client code in \`useEffect\` hook and/or import a third-party library dynamically (if any).`);
+    }
+    return parts.join('\n');
+}
 export default async function render(locals) {
     try {
         return await doRender(locals);
     }
-    catch (err) {
-        // We are not using logger in this file, because it seems to fail with some
-        // compilers / some polyfill methods. This is very likely a bug, but in the
-        // long term, when we output native ES modules in SSR, the bug will be gone.
-        // prettier-ignore
-        console.error(chalk.red(`${chalk.bold('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${chalk.cyan.underline(locals.path)}.`));
-        const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
-        if (isNotDefinedErrorRegex.test(err.message)) {
-            // prettier-ignore
-            console.info(`${chalk.cyan.bold('[INFO]')} It looks like you are using code that should run on the client-side only.
-To get around it, try using ${chalk.cyan('`<BrowserOnly>`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#browseronly')}) or ${chalk.cyan('`ExecutionEnvironment`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#executionenvironment')}).
-It might also require to wrap your client code in ${chalk.cyan('`useEffect`')} hook and/or import a third-party library dynamically (if any).`);
-        }
-        throw err;
+    catch (errorUnknown) {
+        const error = errorUnknown;
+        const message = buildSSRErrorMessage({ error, pathname: locals.path });
+        const ssrError = new Error(message, { cause: error });
+        // It is important to log the error here because the stacktrace causal chain
+        // is not available anymore upper in the tree (this SSR runs in eval)
+        console.error(ssrError);
+        throw ssrError;
     }
 }
 // Renderer for static-site-generator-webpack-plugin (async rendering).
@@ -56,7 +62,7 @@ async function doRender(locals) {
     const routerContext = {};
     const helmetContext = {};
     const linksCollector = createStatefulLinksCollector();
-    const appHtml = ReactDOMServer.renderToString(
+    const app = (
     // @ts-expect-error: we are migrating away from react-loadable anyways
     <Loadable.Capture report={(moduleName) => modules.add(moduleName)}>
       <HelmetProvider context={helmetContext}>
@@ -67,6 +73,7 @@ async function doRender(locals) {
         </StaticRouter>
       </HelmetProvider>
     </Loadable.Capture>);
+    const appHtml = await renderStaticApp(app);
     onLinksCollected(location, linksCollector.getCollectedLinks());
     const { helmet } = helmetContext;
     const htmlAttributes = helmet.htmlAttributes.toString();
@@ -124,7 +131,8 @@ async function doRender(locals) {
     }
     catch (err) {
         // prettier-ignore
-        console.error(chalk.red(`${chalk.bold('[ERROR]')} Minification of page ${chalk.cyan.underline(locals.path)} failed.`));
+        console.error(`Minification of page ${locals.path} failed.`);
+        console.error(err);
         throw err;
     }
 }

package/lib/client/serverRenderer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { ReactNode } from 'react';
+export declare function renderStaticApp(app: ReactNode): Promise<string>;

package/lib/client/serverRenderer.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { renderToPipeableStream } from 'react-dom/server';
+import { Writable } from 'stream';
+export async function renderStaticApp(app) {
+    // Inspired from
+    // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
+    // https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/cache-dir/static-entry.js
+    const writableStream = new WritableAsPromise();
+    const { pipe } = renderToPipeableStream(app, {
+        onError(error) {
+            writableStream.destroy(error);
+        },
+        onAllReady() {
+            pipe(writableStream);
+        },
+    });
+    return writableStream.getPromise();
+}
+// WritableAsPromise inspired by https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/cache-dir/server-utils/writable-as-promise.js
+/* eslint-disable no-underscore-dangle */
+class WritableAsPromise extends Writable {
+    _output;
+    _deferred;
+    constructor() {
+        super();
+        this._output = ``;
+        this._deferred = {
+            promise: null,
+            resolve: () => null,
+            reject: () => null,
+        };
+        this._deferred.promise = new Promise((resolve, reject) => {
+            this._deferred.resolve = resolve;
+            this._deferred.reject = reject;
+        });
+    }
+    _write(chunk, _enc, next) {
+        this._output += chunk.toString();
+        next();
+    }
+    _destroy(error, next) {
+        if (error instanceof Error) {
+            this._deferred.reject(error);
+        }
+        else {
+            next();
+        }
+    }
+    end() {
+        this._deferred.resolve(this._output);
+        return this.destroy();
+    }
+    getPromise() {
+        return this._deferred.promise;
+    }
+}

package/lib/commands/build.d.ts

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { type LoadContextOptions } from '../server';
-export declare type BuildCLIOptions = Pick<LoadContextOptions, 'config' | 'locale' | 'outDir'> & {
+export type BuildCLIOptions = Pick<LoadContextOptions, 'config' | 'locale' | 'outDir'> & {
     bundleAnalyzer?: boolean;
     minify?: boolean;
+    dev?: boolean;
 };
 export declare function build(siteDirParam?: string, cliOptions?: Partial<BuildCLIOptions>, forceTerminate?: boolean): Promise<string>;

package/lib/commands/build.js

@@ -32,6 +32,11 @@ forceTerminate = true) {
     process.env.BABEL_ENV = 'production';
     process.env.NODE_ENV = 'production';
     process.env.DOCUSAURUS_CURRENT_LOCALE = cliOptions.locale;
+    if (cliOptions.dev) {
+        logger_1.default.info `Building in dev mode`;
+        process.env.BABEL_ENV = 'development';
+        process.env.NODE_ENV = 'development';
+    }
     const siteDir = await fs_extra_1.default.realpath(siteDirParam);
     ['SIGINT', 'SIGTERM'].forEach((sig) => {
         process.on(sig, () => process.exit());
@@ -47,8 +52,9 @@ forceTerminate = true) {
             });
         }
         catch (err) {
-            logger_1.default.error `Unable to build website for locale name=${locale}.`;
-            throw err;
+            throw new Error(logger_1.default.interpolate `Unable to build website for locale name=${locale}.`, {
+                cause: err,
+            });
         }
     }
     const context = await (0, server_1.loadContext)({
@@ -96,7 +102,7 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
     // Apply user webpack config.
     const { outDir, generatedFilesDir, plugins, siteConfig: { baseUrl, onBrokenLinks, staticDirectories: staticDirectoriesOption, }, routes, } = props;
     const clientManifestPath = path_1.default.join(generatedFilesDir, 'client-manifest.json');
-    let clientConfig = (0, webpack_merge_1.default)(await (0, client_1.default)(props, cliOptions.minify), {
+    let clientConfig = (0, webpack_merge_1.default)(await (0, client_1.default)(props, cliOptions.minify, true), {
         plugins: [
             // Remove/clean build folders before building bundles.
             new CleanWebpackPlugin_1.default({ verbose: false }),