@docusaurus/core 2.0.0-beta.13 → 2.0.0-beta.15

package/bin/beforeCli.js

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const chalk = require('chalk');
+// @ts-check
+
+const logger = require('@docusaurus/logger').default;
 const fs = require('fs-extra');
 const semver = require('semver');
 const path = require('path');
@@ -53,7 +55,7 @@ try {
   }
 } catch (e) {
   // Do not stop cli if this fails, see https://github.com/facebook/docusaurus/issues/5400
-  console.error(e);
+  logger.error(e);
 }
 
 // We don't want to display update message for canary releases
@@ -74,6 +76,7 @@ if (
   notifier.config.set('update', notifier.update);
 
   if (ignoreUpdate(notifier.update)) {
+    // @ts-expect-error: it works
     return;
   }
 
@@ -91,6 +94,7 @@ if (
     ? `yarn upgrade ${siteDocusaurusPackagesForUpdate}`
     : `npm i ${siteDocusaurusPackagesForUpdate}`;
 
+  /** @type {import('boxen').Options} */
   const boxenOptions = {
     padding: 1,
     margin: 1,
@@ -100,13 +104,12 @@ if (
   };
 
   const docusaurusUpdateMessage = boxen(
-    `Update available ${chalk.dim(`${notifier.update.current}`)}${chalk.reset(
-      ' → ',
-    )}${chalk.green(
-      `${notifier.update.latest}`,
-    )}\n\nTo upgrade Docusaurus packages with the latest version, run the following command:\n${chalk.cyan(
-      `${upgradeCommand}`,
-    )}`,
+    `Update available ${logger.dim(
+      `${notifier.update.current}`,
+    )} → ${logger.green(`${notifier.update.latest}`)}
+
+To upgrade Docusaurus packages with the latest version, run the following command:
+${logger.code(upgradeCommand)}`,
     boxenOptions,
   );
 
@@ -115,11 +118,7 @@ if (
 
 // notify user if node version needs to be updated
 if (!semver.satisfies(process.version, requiredVersion)) {
-  console.log(
-    chalk.red(`\nMinimum Node version not met :(`) +
-      chalk.yellow(
-        `\n\nYou are using Node ${process.version}. We require Node ${requiredVersion} or up!\n`,
-      ),
-  );
+  logger.error('Minimum Node.js version not met :(');
+  logger.info`You are using Node.js number=${process.version}, Requirement: Node.js number=${requiredVersion}.`;
   process.exit(1);
 }

package/bin/docusaurus.js

@@ -6,7 +6,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const chalk = require('chalk');
+// @ts-check
+
+const logger = require('@docusaurus/logger').default;
 const fs = require('fs');
 const cli = require('commander');
 const {
@@ -32,7 +34,7 @@ cli
   .description('Build website.')
   .option(
     '--bundle-analyzer',
-    'visualize size of webpack output files with an interactive zoomable treemap (default: false)',
+    'visualize size of webpack output files with an interactive zoomable tree map (default: false)',
   )
   .option(
     '--out-dir <dir>',
@@ -219,8 +221,7 @@ cli
 
 cli.arguments('<command>').action((cmd) => {
   cli.outputHelp();
-  console.log(`  ${chalk.red(`\n  Unknown command ${chalk.yellow(cmd)}.`)}.`);
-  console.log();
+  logger.error`    Unknown command name=${cmd}.`;
 });
 
 function isInternalCommand(command) {
@@ -238,6 +239,7 @@ function isInternalCommand(command) {
 
 async function run() {
   if (!isInternalCommand(process.argv.slice(2)[0])) {
+    // @ts-expect-error: Hmmm
     await externalCommand(cli, resolveDir('.'));
   }
 
@@ -251,6 +253,6 @@ async function run() {
 run();
 
 process.on('unhandledRejection', (err) => {
-  console.error(chalk.red(err.stack));
+  logger.error(err.stack);
   process.exit(1);
 });

package/lib/babel/preset.d.ts

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { ConfigAPI, TransformOptions } from '@babel/core';
+import type { ConfigAPI, TransformOptions } from '@babel/core';
 declare function babelPresets(api: ConfigAPI): TransformOptions;
 export default babelPresets;

package/lib/choosePort.js

@@ -14,7 +14,7 @@ const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const detect_port_1 = (0, tslib_1.__importDefault)(require("detect-port"));
 const is_root_1 = (0, tslib_1.__importDefault)(require("is-root"));
-const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
 const prompts_1 = (0, tslib_1.__importDefault)(require("prompts"));
 const isInteractive = process.stdout.isTTY;
 const execOptions = {
@@ -53,10 +53,7 @@ function getProcessForPort(port) {
         const processId = getProcessIdOnPort(port);
         const directory = getDirectoryOfProcessById(processId);
         const command = getProcessCommand(processId);
-        return (chalk_1.default.cyan(command) +
-            chalk_1.default.grey(` (pid ${processId})\n`) +
-            chalk_1.default.blue('  in ') +
-            chalk_1.default.cyan(directory));
+        return logger_1.default.interpolate `code=${command} subdue=${`(pid ${processId})`} in path=${directory}`;
     }
     catch (e) {
         return null;
@@ -81,7 +78,9 @@ async function choosePort(host, defaultPort) {
             const question = {
                 type: 'confirm',
                 name: 'shouldChangePort',
-                message: `${chalk_1.default.yellow(`${message}${existingProcess ? ` Probably:\n  ${existingProcess}` : ''}`)}\n\nWould you like to run the app on another port instead?`,
+                message: logger_1.default.yellow(`${logger_1.default.bold('[WARNING]')} ${message}${existingProcess ? ` Probably:\n  ${existingProcess}` : ''}
+
+Would you like to run the app on another port instead?`),
                 initial: true,
             };
             (0, prompts_1.default)(question).then((answer) => {
@@ -94,11 +93,12 @@ async function choosePort(host, defaultPort) {
             });
         }
         else {
-            console.log(chalk_1.default.red(message));
+            logger_1.default.error(message);
             resolve(null);
         }
     }), (err) => {
-        throw new Error(`${chalk_1.default.red(`Could not find an open port at ${chalk_1.default.bold(host)}.`)}\n${`Network error message: "${err.message}".` || err}\n`);
+        throw new Error(`Could not find an open port at ${host}.
+${`Network error message: "${err.message || err}".`}`);
     });
 }
 exports.default = choosePort;

package/lib/client/LinksCollector.d.ts

@@ -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 { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 declare type LinksCollector = {
     collectLink: (link: string) => void;
 };

package/lib/client/PendingNavigation.d.ts

@@ -6,8 +6,8 @@
  */
 /// <reference types="node" />
 import React from 'react';
-import { RouteComponentProps } from 'react-router-dom';
-import { RouteConfig } from 'react-router-config';
+import { type RouteComponentProps } from 'react-router-dom';
+import type { RouteConfig } from 'react-router-config';
 import type { Location } from '@docusaurus/history';
 import './nprogress.css';
 interface Props extends RouteComponentProps {

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

@@ -6,7 +6,7 @@
  */
 /// <reference types="react" />
 declare function BrowserOnly({ children, fallback, }: {
-    children?: () => JSX.Element;
+    children: () => JSX.Element;
     fallback?: JSX.Element;
 }): JSX.Element | null;
 export default BrowserOnly;

package/lib/client/exports/BrowserOnly.js

@@ -4,13 +4,18 @@
  * 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 React, { isValidElement } from 'react';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 // Similar comp to the one described here:
 // https://www.joshwcomeau.com/react/the-perils-of-rehydration/#abstractions
 function BrowserOnly({ children, fallback, }) {
     const isBrowser = useIsBrowser();
-    if (isBrowser && children != null) {
+    if (isBrowser) {
+        if (typeof children !== 'function' &&
+            process.env.NODE_ENV === 'development') {
+            throw new Error(`Docusaurus error: The children of <BrowserOnly> must be a "render function", e.g. <BrowserOnly>{() => <span>{window.location.href}</span>}</BrowserOnly>.
+Current type: ${isValidElement(children) ? 'React element' : typeof children}`);
+        }
         return React.createElement(React.Fragment, null, children());
     }
     return fallback || null;

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="@docusaurus/module-type-aliases" />
-import React, { ReactNode } from 'react';
+import React, { type ReactNode } from 'react';
 import type { Props } from '@docusaurus/ErrorBoundary';
 interface State {
     error: Error | null;

package/lib/client/exports/ErrorBoundary.js

@@ -29,7 +29,9 @@ class ErrorBoundary extends React.Component {
                 tryAgain: () => this.setState({ error: null }),
             });
         }
-        return children;
+        return (children !== null && children !== void 0 ? children : 
+        // See https://github.com/facebook/docusaurus/issues/6337#issuecomment-1012913647
+        null);
     }
 }
 export default ErrorBoundary;

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="@docusaurus/module-type-aliases" />
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { InterpolateProps, InterpolateValues } from '@docusaurus/Interpolate';
 export declare function interpolate<Str extends string>(text: Str, values?: InterpolateValues<Str, string | number>): string;
 export declare function interpolate<Str extends string, Value extends ReactNode>(text: Str, values?: InterpolateValues<Str, Value>): ReactNode;

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

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="@docusaurus/module-type-aliases" />
-import { ReactNode } from 'react';
-import { InterpolateValues } from '@docusaurus/Interpolate';
+import type { ReactNode } from 'react';
+import { type InterpolateValues } from '@docusaurus/Interpolate';
 import type { TranslateParam, TranslateProps } from '@docusaurus/Translate';
 export declare function translate<Str extends string>({ message, id }: TranslateParam<Str>, values?: InterpolateValues<Str, string | number>): string;
 export default function Translate<Str extends string>({ children, id, values, }: TranslateProps<Str>): ReactNode;

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

@@ -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, { ReactNode } from 'react';
+import React, { type ReactNode } from 'react';
 export declare const Context: React.Context<boolean>;
 export declare function BrowserContextProvider({ children, }: {
     children: ReactNode;

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

@@ -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 React, { ReactNode } from 'react';
-import { DocusaurusContext } from '@docusaurus/types';
+import React, { type ReactNode } from 'react';
+import type { DocusaurusContext } from '@docusaurus/types';
 export declare const Context: React.Context<DocusaurusContext>;
 export declare function DocusaurusContextProvider({ children, }: {
     children: ReactNode;

package/lib/client/exports/useBaseUrl.js

@@ -19,7 +19,7 @@ function addBaseUrl(siteUrl, baseUrl, url, { forcePrependBaseUrl = false, absolu
         return url;
     }
     if (forcePrependBaseUrl) {
-        return baseUrl + url;
+        return baseUrl + url.replace(/^\//, '');
     }
     // We should avoid adding the baseurl twice if it's already there
     const shouldAddBaseUrl = !url.startsWith(baseUrl);
@@ -27,7 +27,7 @@ function addBaseUrl(siteUrl, baseUrl, url, { forcePrependBaseUrl = false, absolu
     return absolute ? siteUrl + basePath : basePath;
 }
 export function useBaseUrlUtils() {
-    const { siteConfig: { baseUrl = '/', url: siteUrl } = {} } = useDocusaurusContext();
+    const { siteConfig: { baseUrl, url: siteUrl }, } = useDocusaurusContext();
     return {
         withBaseUrl: (url, options) => addBaseUrl(siteUrl, baseUrl, url, options),
     };

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

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocusaurusContext } from '@docusaurus/types';
+import type { DocusaurusContext } from '@docusaurus/types';
 declare function useDocusaurusContext(): DocusaurusContext;
 export default useDocusaurusContext;

package/lib/client/nprogress.css

@@ -27,10 +27,10 @@
 
 #nprogress .peg {
   position: absolute;
-  right: 0px;
+  right: 0;
   width: 100px;
   height: 100%;
   box-shadow: 0 0 10px #29d, 0 0 5px #29d;
   opacity: 1;
-  transform: rotate(3deg) translate(0px, -4px);
+  transform: rotate(3deg) translate(0, -4px);
 }

package/lib/client/preload.d.ts

@@ -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 { 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.

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,149 +4,109 @@
  * 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 { 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 { minify } from 'html-minifier-terser';
 import path from 'path';
 import fs from 'fs-extra';
 import routes from '@generated/routes';
-import packageJson from '../../package.json';
 import preload from './preload';
 import App from './App';
-import {
-  createStatefulLinksCollector,
-  ProvideLinksCollector,
-} from './LinksCollector';
-import chalk from 'chalk';
+import { createStatefulLinksCollector, ProvideLinksCollector, } from './LinksCollector';
+import logger from '@docusaurus/logger';
 // eslint-disable-next-line no-restricted-imports
-import {memoize} from 'lodash';
-
-const getCompiledSSRTemplate = memoize((template) =>
-  eta.compile(template.trim(), {
+import { memoize } 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 (e) {
+        logger.error `Docusaurus Node/SSR could not render static page with path path=${locals.path} because of following error:
+${e.stack}`;
+        const isNotDefinedErrorRegex = /(window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
+        if (isNotDefinedErrorRegex.test(e.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 new Error('Server-side rendering fails due to the error above.');
     }
-
-    throw new Error('Server-side rendering fails due to the error above.');
-  }
 }
-
 // Renderer for static-site-generator-webpack-plugin (async rendering via promises).
 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,
-  });
-
-  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,
+    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(React.createElement(Loadable.Capture, { report: (moduleName) => modules.add(moduleName) },
+        React.createElement(StaticRouter, { location: location, context: context },
+            React.createElement(ProvideLinksCollector, { linksCollector: linksCollector },
+                React.createElement(App, null)))));
+    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,
     });
-  } catch (e) {
-    console.error(
-      chalk.red(
-        `Minification page with path "${locals.path}" failed because of following error:\n\n${e.stack}\n`,
-      ),
-    );
-    throw e;
-  }
+    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 (e) {
+        logger.error `Minification of page path=${locals.path} failed because of following error:
+${e.stack}`;
+        throw e;
+    }
 }

package/lib/commands/build.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.
  */
-import { BuildCLIOptions } from '@docusaurus/types';
+import type { BuildCLIOptions } from '@docusaurus/types';
 export default function build(siteDir: string, cliOptions?: Partial<BuildCLIOptions>, forceTerminate?: boolean): Promise<string>;