@docusaurus/core 2.0.0-beta.18 → 2.0.0-beta.19

package/bin/beforeCli.mjs

@@ -14,15 +14,21 @@ import path from 'path';
 import updateNotifier from 'update-notifier';
 import boxen from 'boxen';
 import {createRequire} from 'module';
+import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
 
 const packageJson = createRequire(import.meta.url)('../package.json');
-const sitePkg = createRequire(path.join(process.cwd(), 'package.json'))(
-  './package.json',
-);
+/** @type {Record<string, any>} */
+let sitePkg;
+try {
+  sitePkg = createRequire(path.resolve('package.json'))('./package.json');
+} catch {
+  logger.warn`path=${'package.json'} file not found at CWD: path=${process.cwd()}.`;
+  logger.info`This is non-critical, but could lead to undesired behavior downstream. Docusaurus assumes that path=${'package.json'} exists at CWD, because it's where the package manager looks up the script at. A common reason is because you have changed directory in the script. Instead of writing code=${'"start": "cd website && docusaurus start"'}, consider using the code=${'[siteDir]'} argument: code=${'"start": "docusaurus start website"'}.`;
+  sitePkg = {};
+}
 
 const {
   name,
-  version,
   engines: {node: requiredVersion},
 } = packageJson;
 
@@ -40,12 +46,11 @@ export default async function beforeCli() {
   const notifier = updateNotifier({
     pkg: {
       name,
-      version,
+      version: DOCUSAURUS_VERSION,
     },
     // Check is in background so it's fine to use a small value like 1h
     // Use 0 for debugging
     updateCheckInterval: 1000 * 60 * 60,
-    // updateCheckInterval: 0
   });
 
   // Hacky way to ensure we check for updates on first run
@@ -124,7 +129,7 @@ export default async function beforeCli() {
     console.log(docusaurusUpdateMessage);
   }
 
-  // notify user if node version needs to be updated
+  // Notify user if node version needs to be updated
   if (!semver.satisfies(process.version, requiredVersion)) {
     logger.error('Minimum Node.js version not met :(');
     logger.info`You are using Node.js number=${process.version}, Requirement: Node.js number=${requiredVersion}.`;

package/bin/docusaurus.mjs

@@ -11,7 +11,7 @@
 import logger from '@docusaurus/logger';
 import fs from 'fs-extra';
 import cli from 'commander';
-import {createRequire} from 'module';
+import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
 import {
   build,
   swizzle,
@@ -29,9 +29,7 @@ await beforeCli();
 
 const resolveDir = (dir = '.') => fs.realpath(dir);
 
-cli
-  .version(createRequire(import.meta.url)('../package.json').version)
-  .usage('<command> [options]');
+cli.version(DOCUSAURUS_VERSION).usage('<command> [options]');
 
 cli
   .command('build [siteDir]')
@@ -56,14 +54,8 @@ cli
     '--no-minify',
     'build website without minimizing JS bundles (default: false)',
   )
-  .action(async (siteDir, {bundleAnalyzer, config, outDir, locale, minify}) => {
-    build(await resolveDir(siteDir), {
-      bundleAnalyzer,
-      outDir,
-      config,
-      locale,
-      minify,
-    });
+  .action(async (siteDir, options) => {
+    build(await resolveDir(siteDir), options);
   });
 
 cli
@@ -88,9 +80,9 @@ cli
     'copy TypeScript theme files when possible (default: false)',
   )
   .option('--danger', 'enable swizzle for unsafe component of themes')
-  .action(async (themeName, componentName, siteDir, options) => {
-    swizzle(await resolveDir(siteDir), themeName, componentName, options);
-  });
+  .action(async (themeName, componentName, siteDir, options) =>
+    swizzle(await resolveDir(siteDir), themeName, componentName, options),
+  );
 
 cli
   .command('deploy [siteDir]')
@@ -111,13 +103,9 @@ cli
     '--skip-build',
     'skip building website before deploy it (default: false)',
   )
-  .action(async (siteDir, {outDir, skipBuild, config}) => {
-    deploy(await resolveDir(siteDir), {
-      outDir,
-      config,
-      skipBuild,
-    });
-  });
+  .action(async (siteDir, options) =>
+    deploy(await resolveDir(siteDir), options),
+  );
 
 cli
   .command('start [siteDir]')
@@ -138,18 +126,8 @@ cli
     '--poll [interval]',
     'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds',
   )
-  .action(
-    async (siteDir, {port, host, locale, config, hotOnly, open, poll}) => {
-      start(await resolveDir(siteDir), {
-        port,
-        host,
-        locale,
-        config,
-        hotOnly,
-        open,
-        poll,
-      });
-    },
+  .action(async (siteDir, options) =>
+    start(await resolveDir(siteDir), options),
   );
 
 cli
@@ -166,44 +144,25 @@ cli
   .option('-p, --port <port>', 'use specified port (default: 3000)')
   .option('--build', 'build website before serving (default: false)')
   .option('-h, --host <host>', 'use specified host (default: localhost)')
-  .action(
-    async (
-      siteDir,
-      {
-        dir = 'build',
-        port = 3000,
-        host = 'localhost',
-        build: buildSite = false,
-        config,
-      },
-    ) => {
-      serve(await resolveDir(siteDir), {
-        dir,
-        port,
-        build: buildSite,
-        config,
-        host,
-      });
-    },
+  .action(async (siteDir, options) =>
+    serve(await resolveDir(siteDir), options),
   );
 
 cli
   .command('clear [siteDir]')
   .description('Remove build artifacts.')
-  .action(async (siteDir) => {
-    clear(await resolveDir(siteDir));
-  });
+  .action(async (siteDir) => clear(await resolveDir(siteDir)));
 
 cli
   .command('write-translations [siteDir]')
   .description('Extract required translations of your site.')
   .option(
     '-l, --locale <locale>',
-    'the locale folder to write the translations\n"--locale fr" will write translations in ./i18n/fr folder)',
+    'the locale folder to write the translations.\n"--locale fr" will write translations in the ./i18n/fr folder.',
   )
   .option(
     '--override',
-    'by default, we only append missing translation messages to existing translation files. This option allows to override existing translation messages. Make sure to commit or backup your existing translations, as they may be overridden',
+    'By default, we only append missing translation messages to existing translation files. This option allows to override existing translation messages. Make sure to commit or backup your existing translations, as they may be overridden. (default: false)',
   )
   .option(
     '--config <config>',
@@ -211,20 +170,10 @@ cli
   )
   .option(
     '--messagePrefix <messagePrefix>',
-    'allows to init new written messages with a given prefix. This might help you to highlight untranslated message to make them stand out in the UI',
+    'Allows to init new written messages with a given prefix. This might help you to highlight untranslated message by making them stand out in the UI (default: "")',
   )
-  .action(
-    async (
-      siteDir,
-      {locale = undefined, override = false, messagePrefix = '', config},
-    ) => {
-      writeTranslations(await resolveDir(siteDir), {
-        locale,
-        override,
-        config,
-        messagePrefix,
-      });
-    },
+  .action(async (siteDir, options) =>
+    writeTranslations(await resolveDir(siteDir), options),
   );
 
 cli
@@ -274,6 +223,6 @@ if (!process.argv.slice(2).length) {
 cli.parse(process.argv);
 
 process.on('unhandledRejection', (err) => {
-  logger.error(err);
+  logger.error(err instanceof Error ? err.stack : err);
   process.exit(1);
 });

package/lib/client/.eslintrc.js

@@ -11,12 +11,11 @@ module.exports = {
       'error',
       {
         patterns: [
-          // prevent importing lodash in client bundle
-          // prefer shipping vanilla JS
+          // Prevent importing lodash in client bundle for bundle size
           'lodash',
           'lodash.**',
           'lodash/**',
-          // prevent importing server code in client bundle
+          // Prevent importing server code in client bundle
           '**/../babel/**',
           '**/../server/**',
           '**/../commands/**',

package/lib/client/App.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import './client-lifecycles-dispatcher';
+import '@generated/client-modules';
 export default function App(): JSX.Element;

package/lib/client/App.js

@@ -5,20 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
+import '@generated/client-modules';
 import routes from '@generated/routes';
-import renderRoutes from './exports/renderRoutes';
+import { useLocation } from '@docusaurus/router';
+import normalizeLocation from './normalizeLocation';
+import renderRoutes from '@docusaurus/renderRoutes';
 import { BrowserContextProvider } from './browserContext';
 import { DocusaurusContextProvider } from './docusaurusContext';
 import PendingNavigation from './PendingNavigation';
-import BaseUrlIssueBanner from './baseUrlIssueBanner/BaseUrlIssueBanner';
+import BaseUrlIssueBanner from './BaseUrlIssueBanner';
 import SiteMetadataDefaults from './SiteMetadataDefaults';
 import Root from '@theme/Root';
 import SiteMetadata from '@theme/SiteMetadata';
-import './client-lifecycles-dispatcher';
 // TODO, quick fix for CSS insertion order
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
 import Error from '@theme/Error';
 export default function App() {
+    const routeElement = renderRoutes(routes);
+    const location = useLocation();
     return (<ErrorBoundary fallback={Error}>
       <DocusaurusContextProvider>
         <BrowserContextProvider>
@@ -26,8 +30,8 @@ export default function App() {
             <SiteMetadataDefaults />
             <SiteMetadata />
             <BaseUrlIssueBanner />
-            <PendingNavigation routes={routes} delay={1000}>
-              {renderRoutes(routes)}
+            <PendingNavigation location={normalizeLocation(location)}>
+              {routeElement}
             </PendingNavigation>
           </Root>
         </BrowserContextProvider>

package/lib/client/{baseUrlIssueBanner/BaseUrlIssueBanner.d.ts → BaseUrlIssueBanner/index.d.ts}

@@ -6,17 +6,22 @@
  */
 /// <reference types="react" />
 import './styles.module.css';
+declare const InsertBannerWindowAttribute = "__DOCUSAURUS_INSERT_BASEURL_BANNER";
 declare global {
     interface Window {
-        __DOCUSAURUS_INSERT_BASEURL_BANNER: boolean;
+        [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
+ * error). Help message is inlined, and hidden if JS or CSS is able to load.
+ *
+ * This component only inserts the base URL banner for the homepage, to avoid
+ * polluting every statically rendered page.
+ *
  * Note: it might create false positives (ie network failures): not a big deal
- * Note: we only inline this for the homepage to avoid polluting all the site's
- * pages
+ *
  * @see https://github.com/facebook/docusaurus/pull/3621
  */
-export default function BaseUrlIssueBanner(): JSX.Element | null;
+export default function MaybeBaseUrlIssueBanner(): JSX.Element | null;
+export {};

package/lib/client/{baseUrlIssueBanner/BaseUrlIssueBanner.js → BaseUrlIssueBanner/index.js}

@@ -30,7 +30,7 @@ function createInlineHtmlBanner(baseUrl) {
 </div>
 `;
 }
-// fn needs to work for older browsers!
+// Needs to work for older browsers!
 function createInlineScript(baseUrl) {
     return `
 window['${InsertBannerWindowAttribute}'] = true;
@@ -60,7 +60,7 @@ function insertBanner() {
 }
 `;
 }
-function BaseUrlIssueBannerEnabled() {
+function BaseUrlIssueBanner() {
     const { siteConfig: { baseUrl }, } = useDocusaurusContext();
     // useLayoutEffect fires before DOMContentLoaded.
     // It gives the opportunity to avoid inserting the banner in the first place
@@ -68,7 +68,10 @@ function BaseUrlIssueBannerEnabled() {
         window[InsertBannerWindowAttribute] = false;
     }, []);
     return (<>
-      {!ExecutionEnvironment.canUseDOM && (<Head>
+      {!ExecutionEnvironment.canUseDOM && (
+        // Safe to use `ExecutionEnvironment`, because `Head` is purely
+        // side-effect and doesn't affect hydration
+        <Head>
           <script>{createInlineScript(baseUrl)}</script>
         </Head>)}
       <div id={BannerContainerId}/>
@@ -76,17 +79,19 @@ function BaseUrlIssueBannerEnabled() {
 }
 /**
  * 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
+ * error). Help message is inlined, and hidden if JS or CSS is able to load.
+ *
+ * This component only inserts the base URL banner for the homepage, to avoid
+ * polluting every statically rendered page.
+ *
  * Note: it might create false positives (ie network failures): not a big deal
- * Note: we only inline this for the homepage to avoid polluting all the site's
- * pages
+ *
  * @see https://github.com/facebook/docusaurus/pull/3621
  */
-export default function BaseUrlIssueBanner() {
+export default function MaybeBaseUrlIssueBanner() {
     const { siteConfig: { baseUrl, baseUrlIssueBanner }, } = useDocusaurusContext();
     const { pathname } = useLocation();
-    // returns true for the homepage during SRR
     const isHomePage = pathname === baseUrl;
     const enabled = baseUrlIssueBanner && isHomePage;
-    return enabled ? <BaseUrlIssueBannerEnabled /> : null;
+    return enabled ? <BaseUrlIssueBanner /> : null;
 }

package/lib/client/ClientLifecyclesDispatcher.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 ReactElement } from 'react';
+import type { ClientModule } from '@docusaurus/types';
+import type { Location } from 'history';
+export declare function dispatchLifecycleAction<K extends keyof ClientModule>(lifecycleAction: K, ...args: Parameters<NonNullable<ClientModule[K]>>): () => void;
+declare function ClientLifecyclesDispatcher({ children, location, previousLocation, }: {
+    children: ReactElement;
+    location: Location;
+    previousLocation: Location | null;
+}): JSX.Element;
+export default ClientLifecyclesDispatcher;

package/lib/client/ClientLifecyclesDispatcher.js

@@ -0,0 +1,34 @@
+/**
+ * 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 { useLayoutEffect } from 'react';
+import clientModules from '@generated/client-modules';
+export function dispatchLifecycleAction(lifecycleAction, ...args) {
+    const callbacks = clientModules.map((clientModule) => {
+        const lifecycleFunction = (clientModule?.default?.[lifecycleAction] ??
+            clientModule[lifecycleAction]);
+        return lifecycleFunction?.(...args);
+    });
+    return () => callbacks.forEach((cb) => cb?.());
+}
+function ClientLifecyclesDispatcher({ children, location, previousLocation, }) {
+    useLayoutEffect(() => {
+        if (previousLocation !== location) {
+            const { hash } = location;
+            if (!hash) {
+                window.scrollTo(0, 0);
+            }
+            else {
+                const id = decodeURIComponent(hash.substring(1));
+                const element = document.getElementById(id);
+                element?.scrollIntoView();
+            }
+            dispatchLifecycleAction('onRouteDidUpdate', { previousLocation, location });
+        }
+    }, [previousLocation, location]);
+    return children;
+}
+export default ClientLifecyclesDispatcher;

package/lib/client/LinksCollector.js

@@ -17,8 +17,7 @@ export const createStatefulLinksCollector = () => {
 };
 const Context = React.createContext({
     collectLink: () => {
-        // noop by default for client
-        // we only use the broken links checker server-side
+        // No-op for client. We only use the broken links checker server-side.
     },
 });
 export const useLinksCollector = () => useContext(Context);

package/lib/client/PendingNavigation.d.ts

@@ -4,29 +4,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="node" />
 import React from 'react';
-import { type RouteComponentProps } from 'react-router-dom';
-import type { RouteConfig } from 'react-router-config';
 import type { Location } from 'history';
-import './nprogress.css';
-interface Props extends RouteComponentProps {
-    readonly routes: RouteConfig[];
-    readonly delay: number;
+declare type Props = {
     readonly location: Location;
-}
-interface State {
+    readonly children: JSX.Element;
+};
+declare type State = {
     nextRouteHasLoaded: boolean;
-}
+};
 declare class PendingNavigation extends React.Component<Props, State> {
-    previousLocation: Location | null;
-    progressBarTimeout: NodeJS.Timeout | null;
+    private previousLocation;
+    private routeUpdateCleanupCb;
     constructor(props: Props);
     shouldComponentUpdate(nextProps: Props, nextState: State): boolean;
-    private clearProgressBarTimeout;
-    private startProgressBar;
-    private stopProgressBar;
     render(): JSX.Element;
 }
-declare const _default: React.ComponentClass<Pick<Props, "routes" | "delay">, any> & import("react-router").WithRouterStatics<typeof PendingNavigation>;
-export default _default;
+export default PendingNavigation;

package/lib/client/PendingNavigation.js

@@ -5,19 +5,21 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import { Route, withRouter } from 'react-router-dom';
-import nprogress from 'nprogress';
-import clientLifecyclesDispatcher from './client-lifecycles-dispatcher';
+import { Route } from 'react-router-dom';
+import ClientLifecyclesDispatcher, { dispatchLifecycleAction, } from './ClientLifecyclesDispatcher';
+import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import preload from './preload';
-import normalizeLocation from './normalizeLocation';
-import './nprogress.css';
-nprogress.configure({ showSpinner: false });
 class PendingNavigation extends React.Component {
     constructor(props) {
         super(props);
         // previousLocation doesn't affect rendering, hence not stored in state.
         this.previousLocation = null;
-        this.progressBarTimeout = null;
+        this.routeUpdateCleanupCb = ExecutionEnvironment.canUseDOM
+            ? dispatchLifecycleAction('onRouteUpdate', {
+                previousLocation: null,
+                location: this.props.location,
+            })
+            : () => { };
         this.state = {
             nextRouteHasLoaded: true,
         };
@@ -25,72 +27,39 @@ class PendingNavigation extends React.Component {
     // Intercept location update and still show current route until next route
     // is done loading.
     shouldComponentUpdate(nextProps, nextState) {
-        const routeDidChange = nextProps.location !== this.props.location;
-        const { routes, delay } = this.props;
-        // If `routeDidChange` is true, means the router is trying to navigate to a
-        // new route. We will preload the new route.
-        if (routeDidChange) {
-            const nextLocation = normalizeLocation(nextProps.location);
-            this.startProgressBar(delay);
-            // Save the location first.
-            this.previousLocation = normalizeLocation(this.props.location);
-            this.setState({
-                nextRouteHasLoaded: false,
-            });
-            // Load data while the old screen remains.
-            preload(routes, nextLocation.pathname)
-                .then(() => {
-                clientLifecyclesDispatcher.onRouteUpdate({
-                    previousLocation: this.previousLocation,
-                    location: nextLocation,
-                });
-                // Route has loaded, we can reset previousLocation.
-                this.previousLocation = null;
-                this.setState({ nextRouteHasLoaded: true }, this.stopProgressBar);
-                const { hash } = nextLocation;
-                if (!hash) {
-                    window.scrollTo(0, 0);
-                }
-                else {
-                    const id = decodeURIComponent(hash.substring(1));
-                    const element = document.getElementById(id);
-                    if (element) {
-                        element.scrollIntoView();
-                    }
-                }
-            })
-                .catch((e) => console.warn(e));
-            return false;
+        if (nextProps.location === this.props.location) {
+            // `nextRouteHasLoaded` is false means there's a pending route transition.
+            // Don't update until it's done.
+            return nextState.nextRouteHasLoaded;
         }
-        // There's a pending route transition. Don't update until it's done.
-        if (!nextState.nextRouteHasLoaded) {
-            return false;
-        }
-        // Route has loaded, we can update now.
-        return true;
-    }
-    clearProgressBarTimeout() {
-        if (this.progressBarTimeout) {
-            clearTimeout(this.progressBarTimeout);
-            this.progressBarTimeout = null;
-        }
-    }
-    startProgressBar(delay) {
-        this.clearProgressBarTimeout();
-        this.progressBarTimeout = setTimeout(() => {
-            clientLifecyclesDispatcher.onRouteUpdateDelayed({
-                location: normalizeLocation(this.props.location),
-            });
-            nprogress.start();
-        }, delay);
-    }
-    stopProgressBar() {
-        this.clearProgressBarTimeout();
-        nprogress.done();
+        // props.location being different means the router is trying to navigate to
+        // a new route. We will preload the new route.
+        const nextLocation = nextProps.location;
+        // Save the location first.
+        this.previousLocation = this.props.location;
+        this.setState({ nextRouteHasLoaded: false });
+        this.routeUpdateCleanupCb = dispatchLifecycleAction('onRouteUpdate', {
+            previousLocation: this.previousLocation,
+            location: nextLocation,
+        });
+        // Load data while the old screen remains. Force preload instead of using
+        // `window.docusaurus`, because we want to avoid loading screen even when
+        // user is on saveData
+        preload(nextLocation.pathname)
+            .then(() => {
+            this.routeUpdateCleanupCb?.();
+            this.setState({ nextRouteHasLoaded: true });
+        })
+            .catch((e) => console.warn(e));
+        return false;
     }
     render() {
         const { children, location } = this.props;
-        return (<Route location={normalizeLocation(location)} render={() => children}/>);
+        // Use a controlled <Route> to trick all descendants into rendering the old
+        // location.
+        return (<ClientLifecyclesDispatcher previousLocation={this.previousLocation} location={location}>
+        <Route location={location} render={() => children}/>
+      </ClientLifecyclesDispatcher>);
     }
 }
-export default withRouter(PendingNavigation);
+export default PendingNavigation;

package/lib/client/clientEntry.js

@@ -8,7 +8,6 @@ import React from 'react';
 import ReactDOM from 'react-dom';
 import { BrowserRouter } from 'react-router-dom';
 import { HelmetProvider } from 'react-helmet-async';
-import routes from '@generated/routes';
 import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import App from './App';
 import preload from './preload';
@@ -22,7 +21,7 @@ if (ExecutionEnvironment.canUseDOM) {
     // 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(routes, window.location.pathname).then(() => {
+    preload(window.location.pathname).then(() => {
         renderMethod(<HelmetProvider>
         <BrowserRouter>
           <App />

package/lib/client/docusaurus.d.ts

@@ -15,8 +15,8 @@ declare global {
         };
     }
 }
-declare const docusaurus: {
-    prefetch: (routePath: string) => boolean;
-    preload: (routePath: string) => boolean;
-};
-export default docusaurus;
+declare const _default: Readonly<{
+    prefetch(routePath: string): false | Promise<void[]>;
+    preload(routePath: string): false | Promise<void[]>;
+}>;
+export default _default;