@docusaurus/core 0.0.0-5591 → 0.0.0-5599

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)',

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/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/clientEntry.js

@@ -5,29 +5,39 @@
  * 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) {
+            ReactDOM.hydrateRoot(container, app, {
+                onRecoverableError,
+            });
+        }
+        else {
+            const root = ReactDOM.createRoot(container, { onRecoverableError });
+            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/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/client/serverEntry.js

@@ -11,11 +11,11 @@ import fs from 'fs-extra';
 import _ from 'lodash';
 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';
@@ -62,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}>
@@ -73,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();

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

@@ -8,5 +8,6 @@ import { type LoadContextOptions } from '../server';
 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());
@@ -97,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 }),

package/lib/commands/start.js

@@ -89,7 +89,7 @@ async function start(siteDirParam = '.', cliOptions = {}) {
         ...{ pollingOptions },
     });
     ['add', 'change', 'unlink', 'addDir', 'unlinkDir'].forEach((event) => fsWatcher.on(event, reload));
-    let config = (0, webpack_merge_1.default)(await (0, client_1.default)(props, cliOptions.minify), {
+    let config = (0, webpack_merge_1.default)(await (0, client_1.default)(props, cliOptions.minify, false), {
         watchOptions: {
             ignored: /node_modules\/(?!@docusaurus)/,
             poll: cliOptions.poll,

package/lib/webpack/client.d.ts

@@ -6,4 +6,4 @@
  */
 import type { Props } from '@docusaurus/types';
 import type { Configuration } from 'webpack';
-export default function createClientConfig(props: Props, minify?: boolean): Promise<Configuration>;
+export default function createClientConfig(props: Props, minify?: boolean, hydrate?: boolean): Promise<Configuration>;

package/lib/webpack/client.js

@@ -11,10 +11,11 @@ const path_1 = tslib_1.__importDefault(require("path"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const webpack_merge_1 = tslib_1.__importDefault(require("webpack-merge"));
 const webpackbar_1 = tslib_1.__importDefault(require("webpackbar"));
+const webpack_1 = require("webpack");
 const base_1 = require("./base");
 const ChunkAssetPlugin_1 = tslib_1.__importDefault(require("./plugins/ChunkAssetPlugin"));
 const utils_1 = require("./utils");
-async function createClientConfig(props, minify = true) {
+async function createClientConfig(props, minify = true, hydrate = true) {
     const isBuilding = process.argv[2] === 'build';
     const config = await (0, base_1.createBaseConfig)(props, false, minify);
     const clientConfig = (0, webpack_merge_1.default)(config, {
@@ -28,6 +29,9 @@ async function createClientConfig(props, minify = true) {
             runtimeChunk: true,
         },
         plugins: [
+            new webpack_1.DefinePlugin({
+                'process.env.HYDRATE_CLIENT_ENTRY': JSON.stringify(hydrate),
+            }),
             new ChunkAssetPlugin_1.default(),
             // Show compilation progress bar and build time.
             new webpackbar_1.default({

package/lib/webpack/templates/ssr.html.template.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-declare const _default: "\n<!DOCTYPE html>\n<html <%~ it.htmlAttributes %>>\n  <head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"generator\" content=\"Docusaurus v<%= it.version %>\">\n    <% it.metaAttributes.forEach((metaAttribute) => { %>\n      <%~ metaAttribute %>\n    <% }); %>\n    <%~ it.headTags %>\n    <% it.stylesheets.forEach((stylesheet) => { %>\n      <link rel=\"stylesheet\" href=\"<%= it.baseUrl %><%= stylesheet %>\" />\n    <% }); %>\n    <% it.scripts.forEach((script) => { %>\n      <script src=\"<%= it.baseUrl %><%= script %>\" defer></script>\n    <% }); %>\n  </head>\n  <body <%~ it.bodyAttributes %>>\n    <%~ it.preBodyTags %>\n    <div id=\"__docusaurus\">\n      <%~ it.appHtml %>\n    </div>\n    <%~ it.postBodyTags %>\n  </body>\n</html>\n";
+declare const _default: "\n<!DOCTYPE html>\n<html <%~ it.htmlAttributes %>>\n  <head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"generator\" content=\"Docusaurus v<%= it.version %>\">\n    <% it.metaAttributes.forEach((metaAttribute) => { %>\n      <%~ metaAttribute %>\n    <% }); %>\n    <%~ it.headTags %>\n    <% it.stylesheets.forEach((stylesheet) => { %>\n      <link rel=\"stylesheet\" href=\"<%= it.baseUrl %><%= stylesheet %>\" />\n    <% }); %>\n    <% it.scripts.forEach((script) => { %>\n      <script src=\"<%= it.baseUrl %><%= script %>\" defer></script>\n    <% }); %>\n  </head>\n  <body <%~ it.bodyAttributes %>>\n    <%~ it.preBodyTags %>\n    <div id=\"__docusaurus\"><%~ it.appHtml %></div>\n    <%~ it.postBodyTags %>\n  </body>\n</html>\n";
 export default _default;

package/lib/webpack/templates/ssr.html.template.js

@@ -25,9 +25,7 @@ exports.default = `
   </head>
   <body <%~ it.bodyAttributes %>>
     <%~ it.preBodyTags %>
-    <div id="__docusaurus">
-      <%~ it.appHtml %>
-    </div>
+    <div id="__docusaurus"><%~ it.appHtml %></div>
     <%~ it.postBodyTags %>
   </body>
 </html>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "0.0.0-5591",
+  "version": "0.0.0-5599",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -43,13 +43,13 @@
     "@babel/runtime": "^7.21.0",
     "@babel/runtime-corejs3": "^7.21.0",
     "@babel/traverse": "^7.21.2",
-    "@docusaurus/cssnano-preset": "0.0.0-5591",
-    "@docusaurus/logger": "0.0.0-5591",
-    "@docusaurus/mdx-loader": "0.0.0-5591",
+    "@docusaurus/cssnano-preset": "0.0.0-5599",
+    "@docusaurus/logger": "0.0.0-5599",
+    "@docusaurus/mdx-loader": "0.0.0-5599",
     "@docusaurus/react-loadable": "5.5.2",
-    "@docusaurus/utils": "0.0.0-5591",
-    "@docusaurus/utils-common": "0.0.0-5591",
-    "@docusaurus/utils-validation": "0.0.0-5591",
+    "@docusaurus/utils": "0.0.0-5599",
+    "@docusaurus/utils-common": "0.0.0-5599",
+    "@docusaurus/utils-validation": "0.0.0-5599",
     "@slorber/static-site-generator-webpack-plugin": "^4.0.7",
     "@svgr/webpack": "^6.5.1",
     "autoprefixer": "^10.4.13",
@@ -106,8 +106,8 @@
     "webpackbar": "^5.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-5591",
-    "@docusaurus/types": "0.0.0-5591",
+    "@docusaurus/module-type-aliases": "0.0.0-5599",
+    "@docusaurus/types": "0.0.0-5599",
     "@types/detect-port": "^1.3.2",
     "@types/react-dom": "^18.0.11",
     "@types/react-router-config": "^5.0.6",
@@ -116,16 +116,16 @@
     "@types/update-notifier": "^6.0.2",
     "@types/wait-on": "^5.3.1",
     "@types/webpack-bundle-analyzer": "^4.6.0",
-    "react-test-renderer": "^17.0.2",
+    "react-test-renderer": "^18.0.0",
     "tmp-promise": "^3.0.3",
     "tree-node-cli": "^1.6.0"
   },
   "peerDependencies": {
-    "react": "^16.8.4 || ^17.0.0",
-    "react-dom": "^16.8.4 || ^17.0.0"
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
   },
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "29dfa268a45ef335b912fffe4d79ec9a40d92cf9"
+  "gitHead": "b36e4bdd7cd8c3af5d64cc28009c3a73e28721f6"
 }