@docusaurus/core 2.0.0-beta.15d451942 → 2.0.0-beta.18

package/lib/client/prefetch.js

@@ -30,9 +30,9 @@ function linkPrefetchStrategy(url) {
         link.setAttribute('href', url);
         link.onload = resolve;
         link.onerror = reject;
-        const parentElement = document.getElementsByTagName('head')[0] ||
-            document.getElementsByName('script')[0].parentNode;
-        parentElement.appendChild(link);
+        const parentElement = document.getElementsByTagName('head')[0] ??
+            document.getElementsByName('script')[0]?.parentNode;
+        parentElement?.appendChild(link);
     });
 }
 function xhrPrefetchStrategy(url) {
@@ -55,7 +55,7 @@ const supportedPrefetchStrategy = support('prefetch')
     ? linkPrefetchStrategy
     : xhrPrefetchStrategy;
 const preFetched = {};
-function prefetch(url) {
+export default function prefetch(url) {
     return new Promise((resolve) => {
         if (preFetched[url]) {
             resolve();
@@ -66,8 +66,6 @@ function prefetch(url) {
             resolve();
             preFetched[url] = true;
         })
-            // eslint-disable-next-line @typescript-eslint/no-empty-function
             .catch(() => { }); // 404s are logged to the console anyway.
     });
 }
-export default prefetch;

package/lib/client/preload.d.ts

@@ -4,10 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { RouteConfig } from 'react-router-config';
+import { type RouteConfig } from 'react-router-config';
 /**
  * Helper function to make sure all async components for that particular route
- * is preloaded before rendering. This is especially useful to avoid loading screens.
+ * is preloaded before rendering. This is especially useful to avoid loading
+ * screens.
  *
  * @param routes react-router-config
  * @param pathname the route pathname, example: /docs/installation

package/lib/client/preload.js

@@ -7,7 +7,8 @@
 import { matchRoutes } from 'react-router-config';
 /**
  * Helper function to make sure all async components for that particular route
- * is preloaded before rendering. This is especially useful to avoid loading screens.
+ * is preloaded before rendering. This is especially useful to avoid loading
+ * screens.
  *
  * @param routes react-router-config
  * @param pathname the route pathname, example: /docs/installation
@@ -15,13 +16,7 @@ import { matchRoutes } from 'react-router-config';
  */
 export default function preload(routes, pathname) {
     const matches = matchRoutes(routes, pathname);
-    return Promise.all(matches.map((match) => {
-        const { component } = match.route;
-        // @ts-expect-error: ComponentCreator injected this method.
-        if (component && component.preload) {
-            // @ts-expect-error: checked above.
-            return component.preload();
-        }
-        return undefined;
-    }));
+    return Promise.all(
+    // @ts-expect-error: ComponentCreator injected this method.
+    matches.map((match) => match.route.component?.preload?.()));
 }

package/lib/client/routeContext.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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, { type ReactNode } from 'react';
+import type { PluginRouteContext, RouteContext } from '@docusaurus/types';
+export declare const Context: React.Context<PluginRouteContext | null>;
+export declare function RouteContextProvider({ children, value, }: {
+    children: ReactNode;
+    value: PluginRouteContext | RouteContext | null;
+}): JSX.Element;

package/lib/client/routeContext.js

@@ -0,0 +1,31 @@
+/**
+ * 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, { useMemo } from 'react';
+export const Context = React.createContext(null);
+function mergeContexts({ parent, value, }) {
+    if (!parent) {
+        if (!value) {
+            throw new Error('Unexpected: no Docusaurus route context found');
+        }
+        else if (!('plugin' in value)) {
+            throw new Error('Unexpected: Docusaurus topmost route context has no `plugin` attribute');
+        }
+        return value;
+    }
+    // TODO deep merge this
+    const data = { ...parent.data, ...value?.data };
+    return {
+        // nested routes are not supposed to override plugin attribute
+        plugin: parent.plugin,
+        data,
+    };
+}
+export function RouteContextProvider({ children, value, }) {
+    const parent = React.useContext(Context);
+    const mergedValue = useMemo(() => mergeContexts({ parent, value }), [parent, value]);
+    return <Context.Provider value={mergedValue}>{children}</Context.Provider>;
+}

package/lib/client/serverEntry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { Locals } from '@slorber/static-site-generator-webpack-plugin';
+export default function render(locals: Locals & {
+    path: string;
+}): Promise<string>;

package/lib/client/serverEntry.js

@@ -4,165 +4,113 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
 import * as eta from 'eta';
 import React from 'react';
-import {StaticRouter} from 'react-router-dom';
+import { StaticRouter } from 'react-router-dom';
 import ReactDOMServer from 'react-dom/server';
-import {Helmet} from 'react-helmet';
-import {getBundles} from 'react-loadable-ssr-addon-v5-slorber';
+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 { minify } from 'html-minifier-terser';
 import path from 'path';
 import fs from 'fs-extra';
 import routes from '@generated/routes';
-import packageJson from '../../package.json';
-// eslint-disable-next-line import/no-unresolved
 import preload from './preload';
-// eslint-disable-next-line import/no-unresolved
 import App from './App';
-import {
-  createStatefulLinksCollector,
-  ProvideLinksCollector,
-} from './LinksCollector';
-import chalk from 'chalk';
+import { createStatefulLinksCollector, LinksCollectorProvider, } from './LinksCollector';
+import logger from '@docusaurus/logger';
 // eslint-disable-next-line no-restricted-imports
-import {memoize} from 'lodash';
-
-const getCompiledSSRTemplate = memoize((template) => {
-  return eta.compile(template.trim(), {
+import _ from 'lodash';
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const packageJson = require('../../package.json');
+const getCompiledSSRTemplate = _.memoize((template) => eta.compile(template.trim(), {
     rmWhitespace: true,
-  });
-});
-
+}));
 function renderSSRTemplate(ssrTemplate, data) {
-  const compiled = getCompiledSSRTemplate(ssrTemplate);
-  return compiled(data, eta.defaultConfig);
+    const compiled = getCompiledSSRTemplate(ssrTemplate);
+    return compiled(data, eta.defaultConfig);
 }
-
 export default async function render(locals) {
-  try {
-    return await doRender(locals);
-  } catch (e) {
-    console.error(
-      chalk.red(
-        `Docusaurus Node/SSR could not render static page with path "${locals.path}" because of following error:\n\n${e.stack}\n`,
-      ),
-    );
-
-    const isNotDefinedErrorRegex = /(window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
-
-    if (isNotDefinedErrorRegex.test(e.message)) {
-      console.error(
-        chalk.green(
-          'Pro tip: It looks like you are using code that should run on the client-side only.\nTo get around it, try using <BrowserOnly> (https://docusaurus.io/docs/docusaurus-core/#browseronly) or ExecutionEnvironment (https://docusaurus.io/docs/docusaurus-core/#executionenvironment).\nIt might also require to wrap your client code in useEffect hook and/or import a third-party library dynamically (if any).',
-        ),
-      );
+    try {
+        return await doRender(locals);
+    }
+    catch (err) {
+        logger.error `Docusaurus server-side rendering could not render static page with path path=${locals.path}.`;
+        const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
+        if (isNotDefinedErrorRegex.test(err.message)) {
+            logger.info `It looks like you are using code that should run on the client-side only.
+To get around it, try using code=${'<BrowserOnly>'} (path=${'https://docusaurus.io/docs/docusaurus-core/#browseronly'}) or code=${'ExecutionEnvironment'} (path=${'https://docusaurus.io/docs/docusaurus-core/#executionenvironment'}).
+It might also require to wrap your client code in code=${'useEffect'} hook and/or import a third-party library dynamically (if any).`;
+        }
+        throw err;
     }
-
-    throw new Error('Server-side rendering fails due to the error above.');
-  }
 }
-
-// Renderer for static-site-generator-webpack-plugin (async rendering via promises).
+// Renderer for static-site-generator-webpack-plugin (async rendering).
 async function doRender(locals) {
-  const {
-    routesLocation,
-    headTags,
-    preBodyTags,
-    postBodyTags,
-    onLinksCollected,
-    baseUrl,
-    ssrTemplate,
-    noIndex,
-  } = locals;
-  const location = routesLocation[locals.path];
-  await preload(routes, location);
-  const modules = new Set();
-  const context = {};
-
-  const linksCollector = createStatefulLinksCollector();
-  const appHtml = ReactDOMServer.renderToString(
-    <Loadable.Capture report={(moduleName) => modules.add(moduleName)}>
-      <StaticRouter location={location} context={context}>
-        <ProvideLinksCollector linksCollector={linksCollector}>
-          <App />
-        </ProvideLinksCollector>
-      </StaticRouter>
-    </Loadable.Capture>,
-  );
-  onLinksCollected(location, linksCollector.getCollectedLinks());
-
-  const helmet = Helmet.renderStatic();
-  const htmlAttributes = helmet.htmlAttributes.toString();
-  const bodyAttributes = helmet.bodyAttributes.toString();
-  const metaStrings = [
-    helmet.title.toString(),
-    helmet.meta.toString(),
-    helmet.link.toString(),
-    helmet.script.toString(),
-  ];
-  const metaAttributes = metaStrings.filter(Boolean);
-
-  const {generatedFilesDir} = locals;
-  const manifestPath = path.join(generatedFilesDir, 'client-manifest.json');
-  const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
-
-  // Get all required assets for this particular page based on client
-  // manifest information.
-  const modulesToBeLoaded = [...manifest.entrypoints, ...Array.from(modules)];
-  const bundles = getBundles(manifest, modulesToBeLoaded);
-  const stylesheets = (bundles.css || []).map((b) => b.file);
-  const scripts = (bundles.js || []).map((b) => b.file);
-
-  const renderedHtml = renderSSRTemplate(ssrTemplate, {
-    appHtml,
-    baseUrl,
-    htmlAttributes: htmlAttributes || '',
-    bodyAttributes: bodyAttributes || '',
-    headTags,
-    preBodyTags,
-    postBodyTags,
-    metaAttributes,
-    scripts,
-    stylesheets,
-    noIndex,
-    version: packageJson.version,
-  });
-
-  // Minify html with https://github.com/DanielRuf/html-minifier-terser
-  function doMinify() {
-    return minify(renderedHtml, {
-      removeComments: true,
-      removeRedundantAttributes: true,
-      removeEmptyAttributes: true,
-      removeScriptTypeAttributes: true,
-      removeStyleLinkTypeAttributes: true,
-      useShortDoctype: true,
-      minifyJS: true,
+    const { routesLocation, headTags, preBodyTags, postBodyTags, onLinksCollected, baseUrl, ssrTemplate, noIndex, } = locals;
+    const location = routesLocation[locals.path];
+    await preload(routes, location);
+    const modules = new Set();
+    const context = {};
+    const helmetContext = {};
+    const linksCollector = createStatefulLinksCollector();
+    const appHtml = ReactDOMServer.renderToString(<Loadable.Capture report={(moduleName) => modules.add(moduleName)}>
+      <HelmetProvider context={helmetContext}>
+        <StaticRouter location={location} context={context}>
+          <LinksCollectorProvider linksCollector={linksCollector}>
+            <App />
+          </LinksCollectorProvider>
+        </StaticRouter>
+      </HelmetProvider>
+    </Loadable.Capture>);
+    onLinksCollected(location, linksCollector.getCollectedLinks());
+    const { helmet } = helmetContext;
+    const htmlAttributes = helmet.htmlAttributes.toString();
+    const bodyAttributes = helmet.bodyAttributes.toString();
+    const metaStrings = [
+        helmet.title.toString(),
+        helmet.meta.toString(),
+        helmet.link.toString(),
+        helmet.script.toString(),
+    ];
+    const metaAttributes = metaStrings.filter(Boolean);
+    const { generatedFilesDir } = locals;
+    const manifestPath = path.join(generatedFilesDir, 'client-manifest.json');
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    // Get all required assets for this particular page based on client
+    // manifest information.
+    const modulesToBeLoaded = [...manifest.entrypoints, ...Array.from(modules)];
+    const bundles = getBundles(manifest, modulesToBeLoaded);
+    const stylesheets = (bundles.css ?? []).map((b) => b.file);
+    const scripts = (bundles.js ?? []).map((b) => b.file);
+    const renderedHtml = renderSSRTemplate(ssrTemplate, {
+        appHtml,
+        baseUrl,
+        htmlAttributes,
+        bodyAttributes,
+        headTags,
+        preBodyTags,
+        postBodyTags,
+        metaAttributes,
+        scripts,
+        stylesheets,
+        noIndex,
+        version: packageJson.version,
     });
-  }
-
-  // TODO this is a temporary error affecting only monorepos due to Terser 5 (async) being used by html-minifier-terser,
-  // instead of the expected Terser 4 (sync)
-  // TODO, remove this once we upgrade everything to Terser 5 (https://github.com/terser/html-minifier-terser/issues/46)
-  // See also
-  // - https://github.com/facebook/docusaurus/issues/3515
-  // - https://github.com/terser/html-minifier-terser/issues/49
-  try {
-    return doMinify();
-  } catch (e) {
-    if (
-      e.message &&
-      e.message.includes("Cannot read property 'replace' of undefined")
-    ) {
-      console.error(
-        chalk.red(
-          '\nDocusaurus user: you probably have this known error due to using a monorepo/workspace.\nWe have a workaround for you, check https://github.com/facebook/docusaurus/issues/3515\n',
-        ),
-      );
+    try {
+        // Minify html with https://github.com/DanielRuf/html-minifier-terser
+        return await minify(renderedHtml, {
+            removeComments: false,
+            removeRedundantAttributes: true,
+            removeEmptyAttributes: true,
+            removeScriptTypeAttributes: true,
+            removeStyleLinkTypeAttributes: true,
+            useShortDoctype: true,
+            minifyJS: true,
+        });
+    }
+    catch (err) {
+        logger.error `Minification of page path=${locals.path} failed.`;
+        throw err;
     }
-    throw e;
-  }
 }

package/lib/client/theme-fallback/Error/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/// <reference types="@docusaurus/module-type-aliases" />
+/// <reference types="react" />
+import type { Props } from '@theme/Error';
+export default function Error({ error, tryAgain }: Props): JSX.Element;

package/lib/client/theme-fallback/Error/index.js

@@ -0,0 +1,43 @@
+/**
+ * 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 Layout from '@theme/Layout';
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import Head from '@docusaurus/Head';
+function ErrorDisplay({ error, tryAgain }) {
+    return (<div style={{
+            display: 'flex',
+            flexDirection: 'column',
+            justifyContent: 'center',
+            alignItems: 'center',
+            height: '50vh',
+            width: '100%',
+            fontSize: '20px',
+        }}>
+      <h1>This page crashed.</h1>
+      <p>{error.message}</p>
+      <button type="button" onClick={tryAgain}>
+        Try again
+      </button>
+    </div>);
+}
+export default function Error({ error, tryAgain }) {
+    // We wrap the error in its own error boundary because the layout can actually
+    // throw too... Only the ErrorDisplay component is simple enough to be
+    // considered safe to never throw
+    return (<ErrorBoundary 
+    // Note: we display the original error here, not the error that we
+    // captured in this extra error boundary
+    fallback={() => <ErrorDisplay error={error} tryAgain={tryAgain}/>}>
+      <Head>
+        <title>Page Error</title>
+      </Head>
+      <Layout>
+        <ErrorDisplay error={error} tryAgain={tryAgain}/>
+      </Layout>
+    </ErrorBoundary>);
+}

package/lib/client/theme-fallback/Layout/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/// <reference types="@docusaurus/module-type-aliases" />
+/// <reference types="react" />
+import type { Props } from '@theme/Layout';
+export default function Layout({ children }: Props): JSX.Element;

package/lib/client/theme-fallback/Layout/index.js

@@ -4,31 +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 from 'react';
-import Head from '@docusaurus/Head';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import useBaseUrl from '@docusaurus/useBaseUrl';
-
-function Layout(props) {
-  const context = useDocusaurusContext();
-  const {siteConfig = {}} = context;
-  const {favicon, tagline = '', title: defaultTitle} = siteConfig;
-  const {children, title, description} = props;
-  const faviconUrl = useBaseUrl(favicon);
-  return (
-    <>
-      <Head defaultTitle={`${defaultTitle}${tagline ? ` · ${tagline}` : ''}`}>
-        {title && <title>{`${title} · ${tagline}`}</title>}
-        {favicon && <link rel="shortcut icon" href={faviconUrl} />}
-        {description && <meta name="description" content={description} />}
-        {description && (
-          <meta property="og:description" content={description} />
-        )}
-      </Head>
-      {children}
-    </>
-  );
+export default function Layout({ children }) {
+    return <>{children}</>;
 }
-
-export default Layout;

package/lib/client/theme-fallback/Loading/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+import type { LoadingComponentProps } from 'react-loadable';
+export default function Loading({ error, retry, pastDelay, }: LoadingComponentProps): JSX.Element | null;