@docusaurus/core 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

package/lib/client/serverEntry.js

@@ -4,165 +4,127 @@
  * 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 ReactDOMServer from 'react-dom/server';
-import {Helmet} from 'react-helmet';
-import {getBundles} from 'react-loadable-ssr-addon-v5-slorber';
-import Loadable from 'react-loadable';
-
-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
+// 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 preload from './preload';
-// eslint-disable-next-line import/no-unresolved
 import App from './App';
-import {
-  createStatefulLinksCollector,
-  ProvideLinksCollector,
-} from './LinksCollector';
-import chalk from 'chalk';
-// eslint-disable-next-line no-restricted-imports
-import {memoize} from 'lodash';
-
-const getCompiledSSRTemplate = memoize((template) => {
-  return eta.compile(template.trim(), {
+import { createStatefulLinksCollector, LinksCollectorProvider, } from './LinksCollector';
+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) {
+        // 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;
     }
-
-    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(
+    const { routesLocation, headTags, preBodyTags, postBodyTags, onLinksCollected, onHeadTagsCollected, baseUrl, ssrTemplate, noIndex, DOCUSAURUS_VERSION, } = locals;
+    const location = routesLocation[locals.path];
+    await preload(location);
+    const modules = new Set();
+    const routerContext = {};
+    const helmetContext = {};
+    const linksCollector = createStatefulLinksCollector();
+    const appHtml = ReactDOMServer.renderToString(
+    // @ts-expect-error: we are migrating away from react-loadable anyways
     <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,
+      <HelmetProvider context={helmetContext}>
+        <StaticRouter location={location} context={routerContext}>
+          <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(),
+    ];
+    onHeadTagsCollected(location, helmet);
+    const metaAttributes = metaStrings.filter(Boolean);
+    const { generatedFilesDir } = locals;
+    const manifestPath = path.join(generatedFilesDir, 'client-manifest.json');
+    // Using readJSON seems to fail for users of some plugins, possibly because of
+    // the eval sandbox having a different `Buffer` instance (native one instead
+    // of polyfilled one)
+    const manifest = (await fs
+        .readFile(manifestPath, 'utf-8')
+        .then(JSON.parse));
+    // 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: DOCUSAURUS_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, please see https://github.com/facebook/docusaurus/issues/3515\n',
-        ),
-      );
+    try {
+        if (process.env.SKIP_HTML_MINIFICATION === 'true') {
+            return renderedHtml;
+        }
+        // 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) {
+        // prettier-ignore
+        console.error(chalk.red(`${chalk.bold('[ERROR]')} Minification of page ${chalk.cyan.underline(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,45 @@
+/**
+ * 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.
+ */
+// Should we translate theme-fallback?
+/* eslint-disable @docusaurus/no-untranslated-text */
+import React from 'react';
+import Head from '@docusaurus/Head';
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import Layout from '@theme/Layout';
+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;

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

@@ -4,133 +4,67 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
+// Should we translate theme-fallback?
+/* eslint-disable @docusaurus/no-untranslated-text */
 import React from 'react';
-
-export default ({error, retry, pastDelay}) => {
-  if (error) {
-    return (
-      <div
-        style={{
-          align: 'center',
-          color: '#fff',
-          backgroundColor: '#fa383e',
-          borderColor: '#fa383e',
-          borderStyle: 'solid',
-          borderRadius: '0.25rem',
-          borderWidth: '1px',
-          boxSizing: 'border-box',
-          display: 'block',
-          padding: '1rem',
-          flex: '0 0 50%',
-          marginLeft: '25%',
-          marginRight: '25%',
-          marginTop: '5rem',
-          maxWidth: '50%',
-          width: '100%',
-        }}>
-        <p>{error.message}</p>
+export default function Loading({ error, retry, pastDelay, }) {
+    if (error) {
+        return (<div style={{
+                textAlign: 'center',
+                color: '#fff',
+                backgroundColor: '#fa383e',
+                borderColor: '#fa383e',
+                borderStyle: 'solid',
+                borderRadius: '0.25rem',
+                borderWidth: '1px',
+                boxSizing: 'border-box',
+                display: 'block',
+                padding: '1rem',
+                flex: '0 0 50%',
+                marginLeft: '25%',
+                marginRight: '25%',
+                marginTop: '5rem',
+                maxWidth: '50%',
+                width: '100%',
+            }}>
+        <p>{String(error)}</p>
         <div>
           <button type="button" onClick={retry}>
             Retry
           </button>
         </div>
-      </div>
-    );
-  }
-
-  if (pastDelay) {
-    return (
-      <div
-        style={{
-          display: 'flex',
-          justifyContent: 'center',
-          alignItems: 'center',
-          height: '100vh',
-        }}>
-        <svg
-          id="loader"
-          style={{
-            width: 128,
-            height: 110,
-            position: 'absolute',
-            top: 'calc(100vh - 64%)',
-          }}
-          viewBox="0 0 45 45"
-          xmlns="http://www.w3.org/2000/svg"
-          stroke="#61dafb">
-          <g
-            fill="none"
-            fillRule="evenodd"
-            transform="translate(1 1)"
-            strokeWidth="2">
+      </div>);
+    }
+    if (pastDelay) {
+        return (<div style={{
+                display: 'flex',
+                justifyContent: 'center',
+                alignItems: 'center',
+                height: '100vh',
+            }}>
+        <svg id="loader" style={{
+                width: 128,
+                height: 110,
+                position: 'absolute',
+                top: 'calc(100vh - 64%)',
+            }} viewBox="0 0 45 45" xmlns="http://www.w3.org/2000/svg" stroke="#61dafb">
+          <g fill="none" fillRule="evenodd" transform="translate(1 1)" strokeWidth="2">
             <circle cx="22" cy="22" r="6" strokeOpacity="0">
-              <animate
-                attributeName="r"
-                begin="1.5s"
-                dur="3s"
-                values="6;22"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
-              <animate
-                attributeName="stroke-opacity"
-                begin="1.5s"
-                dur="3s"
-                values="1;0"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
-              <animate
-                attributeName="stroke-width"
-                begin="1.5s"
-                dur="3s"
-                values="2;0"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
+              <animate attributeName="r" begin="1.5s" dur="3s" values="6;22" calcMode="linear" repeatCount="indefinite"/>
+              <animate attributeName="stroke-opacity" begin="1.5s" dur="3s" values="1;0" calcMode="linear" repeatCount="indefinite"/>
+              <animate attributeName="stroke-width" begin="1.5s" dur="3s" values="2;0" calcMode="linear" repeatCount="indefinite"/>
             </circle>
             <circle cx="22" cy="22" r="6" strokeOpacity="0">
-              <animate
-                attributeName="r"
-                begin="3s"
-                dur="3s"
-                values="6;22"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
-              <animate
-                attributeName="stroke-opacity"
-                begin="3s"
-                dur="3s"
-                values="1;0"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
-              <animate
-                attributeName="stroke-width"
-                begin="3s"
-                dur="3s"
-                values="2;0"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
+              <animate attributeName="r" begin="3s" dur="3s" values="6;22" calcMode="linear" repeatCount="indefinite"/>
+              <animate attributeName="stroke-opacity" begin="3s" dur="3s" values="1;0" calcMode="linear" repeatCount="indefinite"/>
+              <animate attributeName="stroke-width" begin="3s" dur="3s" values="2;0" calcMode="linear" repeatCount="indefinite"/>
             </circle>
             <circle cx="22" cy="22" r="8">
-              <animate
-                attributeName="r"
-                begin="0s"
-                dur="1.5s"
-                values="6;1;2;3;4;5;6"
-                calcMode="linear"
-                repeatCount="indefinite"
-              />
+              <animate attributeName="r" begin="0s" dur="1.5s" values="6;1;2;3;4;5;6" calcMode="linear" repeatCount="indefinite"/>
             </circle>
           </g>
         </svg>
-      </div>
-    );
-  }
-
-  return null;
-};
+      </div>);
+    }
+    return null;
+}

package/lib/{server/html-tags/htmlTags.d.ts → client/theme-fallback/NotFound/index.d.ts}

@@ -4,4 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export default function htmlTagObjectToString(tagDefinition: unknown): string;
+/// <reference types="react" />
+export default function NotFound(): JSX.Element;

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

@@ -4,25 +4,26 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
+// Should we translate theme-fallback?
+/* eslint-disable @docusaurus/no-untranslated-text */
 import React from 'react';
+import Head from '@docusaurus/Head';
 import Layout from '@theme/Layout';
-
-function NotFound() {
-  return (
-    <Layout title="Page Not Found">
-      <div
-        style={{
-          display: 'flex',
-          justifyContent: 'center',
-          alignItems: 'center',
-          height: '50vh',
-          fontSize: '20px',
+export default function NotFound() {
+    return (<>
+      <Head>
+        <title>Page Not Found</title>
+      </Head>
+      <Layout>
+        <div style={{
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+            height: '50vh',
+            fontSize: '20px',
         }}>
-        <h1>Oops, page not found </h1>
-      </div>
-    </Layout>
-  );
+          <h1>Oops, page not found </h1>
+        </div>
+      </Layout>
+    </>);
 }
-
-export default NotFound;

package/lib/client/theme-fallback/Root/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/Root';
+export default function Root({ children }: Props): JSX.Element;