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

package/lib/server/routes.js

@@ -6,115 +6,202 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRoutes = exports.handleDuplicateRoutes = exports.genChunkName = void 0;
+const tslib_1 = require("tslib");
+const querystring_1 = tslib_1.__importDefault(require("querystring"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
-const lodash_1 = require("lodash");
-const querystring_1 = require("querystring");
-const createRouteCodeString = ({ routePath, routeHash, exact, subroutesCodeStrings, }) => {
-    const str = `{
-  path: '${routePath}',
-  component: ComponentCreator('${routePath}','${routeHash}'),
-  ${exact ? `exact: true,` : ''}
-${subroutesCodeStrings
-        ? `  routes: [
-${utils_1.removeSuffix(subroutesCodeStrings.join(',\n'), ',\n')},
-]
-`
-        : ''}}`;
-    return str;
-};
-const NotFoundRouteCode = `{
-  path: '*',
-  component: ComponentCreator('*')
-}`;
-const RoutesImportsCode = [
-    `import React from 'react';`,
-    `import ComponentCreator from '@docusaurus/ComponentCreator';`,
-].join('\n');
-function isModule(value) {
-    if (lodash_1.isString(value)) {
-        return true;
+const utils_2 = require("./utils");
+/** Indents every line of `str` by one level. */
+function indent(str) {
+    return `  ${str.replace(/\n/g, `\n  `)}`;
+}
+const chunkNameCache = new Map();
+/**
+ * Generates a unique chunk name that can be used in the chunk registry.
+ *
+ * @param modulePath A path to generate chunk name from. The actual value has no
+ * semantic significance.
+ * @param prefix A prefix to append to the chunk name, to avoid name clash.
+ * @param preferredName Chunk names default to `modulePath`, and this can supply
+ * a more human-readable name.
+ * @param shortId When `true`, the chunk name would only be a hash without any
+ * other characters. Useful for bundle size. Defaults to `true` in production.
+ */
+function genChunkName(modulePath, prefix, preferredName, shortId = process.env.NODE_ENV === 'production') {
+    let chunkName = chunkNameCache.get(modulePath);
+    if (!chunkName) {
+        if (shortId) {
+            chunkName = (0, utils_1.simpleHash)(modulePath, 8);
+        }
+        else {
+            let str = modulePath;
+            if (preferredName) {
+                const shortHash = (0, utils_1.simpleHash)(modulePath, 3);
+                str = `${preferredName}${shortHash}`;
+            }
+            const name = str === '/' ? 'index' : (0, utils_1.docuHash)(str);
+            chunkName = prefix ? `${prefix}---${name}` : name;
+        }
+        chunkNameCache.set(modulePath, chunkName);
+    }
+    return chunkName;
+}
+exports.genChunkName = genChunkName;
+/**
+ * Takes a piece of route config, and serializes it into raw JS code. The shape
+ * is the same as react-router's `RouteConfig`. Formatting is similar to
+ * `JSON.stringify` but without all the quotes.
+ */
+function serializeRouteConfig({ routePath, routeHash, exact, subroutesCodeStrings, props, }) {
+    const parts = [
+        `path: '${routePath}'`,
+        `component: ComponentCreator('${routePath}', '${routeHash}')`,
+    ];
+    if (exact) {
+        parts.push(`exact: true`);
     }
-    if (lodash_1.isPlainObject(value) && lodash_1.has(value, '__import') && lodash_1.has(value, 'path')) {
-        return true;
+    if (subroutesCodeStrings) {
+        parts.push(`routes: [
+${indent(subroutesCodeStrings.join(',\n'))}
+]`);
     }
-    return false;
+    Object.entries(props).forEach(([propName, propValue]) => {
+        // Inspired by https://github.com/armanozak/should-quote/blob/main/packages/should-quote/src/lib/should-quote.ts
+        const shouldQuote = ((key) => {
+            // Pre-sanitation to prevent injection
+            if (/[.,;:}/\s]/.test(key)) {
+                return true;
+            }
+            try {
+                // If this key can be used in an expression like ({a:0}).a
+                // eslint-disable-next-line no-eval
+                eval(`({${key}:0}).${key}`);
+                return false;
+            }
+            catch {
+                return true;
+            }
+        })(propName);
+        // Escape quotes as well
+        const key = shouldQuote ? JSON.stringify(propName) : propName;
+        parts.push(`${key}: ${JSON.stringify(propValue)}`);
+    });
+    return `{
+${indent(parts.join(',\n'))}
+}`;
 }
+const isModule = (value) => typeof value === 'string' ||
+    (typeof value === 'object' &&
+        // eslint-disable-next-line no-underscore-dangle
+        !!value?.__import);
+/**
+ * Takes a {@link Module} (which is nothing more than a path plus some metadata
+ * like query) and returns the string path it represents.
+ */
 function getModulePath(target) {
     if (typeof target === 'string') {
         return target;
     }
-    const queryStr = target.query ? `?${querystring_1.stringify(target.query)}` : '';
+    const queryStr = target.query ? `?${querystring_1.default.stringify(target.query)}` : '';
     return `${target.path}${queryStr}`;
 }
-async function loadRoutes(pluginsRouteConfigs, baseUrl) {
-    const registry = {};
-    const routesPaths = [utils_1.normalizeUrl([baseUrl, '404.html'])];
-    const routesChunkNames = {};
-    // This is the higher level overview of route code generation.
-    function generateRouteCode(routeConfig) {
-        const { path: routePath, component, modules = {}, routes: subroutes, exact, } = routeConfig;
-        if (!lodash_1.isString(routePath) || !component) {
-            throw new Error(`Invalid routeConfig (Path must be a string and component is required) \n${JSON.stringify(routeConfig)}`);
-        }
-        // Collect all page paths for injecting it later in the plugin lifecycle
-        // This is useful for plugins like sitemaps, redirects etc...
-        // If a route has subroutes, it is not necessarily a valid page path (more likely to be a wrapper)
-        if (!subroutes) {
-            routesPaths.push(routePath);
-        }
-        // We hash the route to generate the key, because 2 routes can conflict with
-        // each others if they have the same path, ex: parent=/docs, child=/docs
-        // see https://github.com/facebook/docusaurus/issues/2917
-        const routeHash = utils_1.simpleHash(JSON.stringify(routeConfig), 3);
-        const chunkNamesKey = `${routePath}-${routeHash}`;
-        routesChunkNames[chunkNamesKey] = {
-            ...genRouteChunkNames(registry, { component }, 'component', component),
-            ...genRouteChunkNames(registry, modules, 'module', routePath),
-        };
-        return createRouteCodeString({
-            routePath: routeConfig.path.replace(/'/g, "\\'"),
-            routeHash,
-            exact,
-            subroutesCodeStrings: subroutes === null || subroutes === void 0 ? void 0 : subroutes.map(generateRouteCode),
-        });
+function genChunkNames(routeModule, prefix, name, res) {
+    if (isModule(routeModule)) {
+        // This is a leaf node, no need to recurse
+        const modulePath = getModulePath(routeModule);
+        const chunkName = genChunkName(modulePath, prefix, name);
+        res.registry[chunkName] = (0, utils_1.escapePath)(modulePath);
+        return chunkName;
     }
-    const routesConfig = `
-${RoutesImportsCode}
-export default [
-${pluginsRouteConfigs.map(generateRouteCode).join(',\n')},
-${NotFoundRouteCode}
-];\n`;
-    return {
-        registry,
-        routesConfig,
-        routesChunkNames,
-        routesPaths,
-    };
+    if (Array.isArray(routeModule)) {
+        return routeModule.map((val, index) => genChunkNames(val, `${index}`, name, res));
+    }
+    return lodash_1.default.mapValues(routeModule, (v, key) => genChunkNames(v, key, name, res));
 }
-exports.default = loadRoutes;
-function genRouteChunkNames(
-// TODO instead of passing a mutating the registry, return a registry slice?
-registry, value, prefix, name) {
-    if (!value) {
-        return null;
+function handleDuplicateRoutes(pluginsRouteConfigs, onDuplicateRoutes) {
+    if (onDuplicateRoutes === 'ignore') {
+        return;
     }
-    if (Array.isArray(value)) {
-        return value.map((val, index) => genRouteChunkNames(registry, val, `${index}`, name));
+    const allRoutes = (0, utils_2.getAllFinalRoutes)(pluginsRouteConfigs).map((routeConfig) => routeConfig.path);
+    const seenRoutes = new Set();
+    const duplicatePaths = allRoutes.filter((route) => {
+        if (seenRoutes.has(route)) {
+            return true;
+        }
+        seenRoutes.add(route);
+        return false;
+    });
+    if (duplicatePaths.length > 0) {
+        logger_1.default.report(onDuplicateRoutes) `Duplicate routes found!${duplicatePaths.map((duplicateRoute) => logger_1.default.interpolate `Attempting to create page at url=${duplicateRoute}, but a page already exists at this route.`)}
+This could lead to non-deterministic routing behavior.`;
     }
-    if (isModule(value)) {
-        const modulePath = getModulePath(value);
-        const chunkName = utils_1.genChunkName(modulePath, prefix, name);
-        // We need to JSON.stringify so that if its on windows, backslashes are escaped.
-        const loader = `() => import(/* webpackChunkName: '${chunkName}' */ ${JSON.stringify(modulePath)})`;
-        registry[chunkName] = {
-            loader,
-            modulePath,
-        };
-        return chunkName;
+}
+exports.handleDuplicateRoutes = handleDuplicateRoutes;
+/**
+ * This is the higher level overview of route code generation. For each route
+ * config node, it returns the node's serialized form, and mutates `registry`,
+ * `routesPaths`, and `routesChunkNames` accordingly.
+ */
+function genRouteCode(routeConfig, res) {
+    const { path: routePath, component, modules = {}, context, routes: subroutes, priority, exact, ...props } = routeConfig;
+    if (typeof routePath !== 'string' || !component) {
+        throw new Error(`Invalid route config: path must be a string and component is required.
+${JSON.stringify(routeConfig)}`);
     }
-    const newValue = {};
-    Object.keys(value).forEach((key) => {
-        newValue[key] = genRouteChunkNames(registry, value[key], key, name);
+    if (!subroutes) {
+        res.routesPaths.push(routePath);
+    }
+    const routeHash = (0, utils_1.simpleHash)(JSON.stringify(routeConfig), 3);
+    res.routesChunkNames[`${routePath}-${routeHash}`] = {
+        // Avoid clash with a prop called "component"
+        ...genChunkNames({ __comp: component }, 'component', component, res),
+        ...(context &&
+            genChunkNames({ __context: context }, 'context', routePath, res)),
+        ...genChunkNames(modules, 'module', routePath, res),
+    };
+    return serializeRouteConfig({
+        routePath: routePath.replace(/'/g, "\\'"),
+        routeHash,
+        subroutesCodeStrings: subroutes?.map((r) => genRouteCode(r, res)),
+        exact,
+        props,
     });
-    return newValue;
 }
+/**
+ * Routes are prepared into three temp files:
+ *
+ * - `routesConfig`, the route config passed to react-router. This file is kept
+ * minimal, because it can't be code-splitted.
+ * - `routesChunkNames`, a mapping from route paths (hashed) to code-splitted
+ * chunk names.
+ * - `registry`, a mapping from chunk names to options for react-loadable.
+ */
+function loadRoutes(routeConfigs, baseUrl, onDuplicateRoutes) {
+    handleDuplicateRoutes(routeConfigs, onDuplicateRoutes);
+    const res = {
+        // To be written by `genRouteCode`
+        routesConfig: '',
+        routesChunkNames: {},
+        registry: {},
+        routesPaths: [(0, utils_1.normalizeUrl)([baseUrl, '404.html'])],
+    };
+    // `genRouteCode` would mutate `res`
+    const routeConfigSerialized = routeConfigs
+        .map((r) => genRouteCode(r, res))
+        .join(',\n');
+    res.routesConfig = `import React from 'react';
+import ComponentCreator from '@docusaurus/ComponentCreator';
+
+export default [
+${indent(routeConfigSerialized)},
+  {
+    path: '*',
+    component: ComponentCreator('*'),
+  },
+];
+`;
+    return res;
+}
+exports.loadRoutes = loadRoutes;

package/lib/server/siteMetadata.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 { LoadedPlugin, PluginVersionInformation, SiteMetadata } from '@docusaurus/types';
+export declare function getPluginVersion(pluginPath: string, siteDir: string): Promise<PluginVersionInformation>;
+export declare function loadSiteMetadata({ plugins, siteDir, }: {
+    plugins: LoadedPlugin[];
+    siteDir: string;
+}): Promise<SiteMetadata>;

package/lib/server/siteMetadata.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSiteMetadata = exports.getPluginVersion = void 0;
+const tslib_1 = require("tslib");
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+async function getPackageJsonVersion(packageJsonPath) {
+    if (await fs_extra_1.default.pathExists(packageJsonPath)) {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
+        return require(packageJsonPath).version;
+    }
+    return undefined;
+}
+async function getPackageJsonName(packageJsonPath) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
+    return require(packageJsonPath).name;
+}
+async function getPluginVersion(pluginPath, siteDir) {
+    let potentialPluginPackageJsonDirectory = path_1.default.dirname(pluginPath);
+    while (potentialPluginPackageJsonDirectory !== '/') {
+        const packageJsonPath = path_1.default.join(potentialPluginPackageJsonDirectory, 'package.json');
+        if ((await fs_extra_1.default.pathExists(packageJsonPath)) &&
+            (await fs_extra_1.default.lstat(packageJsonPath)).isFile()) {
+            if (potentialPluginPackageJsonDirectory === siteDir) {
+                // If the plugin belongs to the same docusaurus project, we classify it
+                // as local plugin.
+                return { type: 'project' };
+            }
+            return {
+                type: 'package',
+                name: await getPackageJsonName(packageJsonPath),
+                version: await getPackageJsonVersion(packageJsonPath),
+            };
+        }
+        potentialPluginPackageJsonDirectory = path_1.default.dirname(potentialPluginPackageJsonDirectory);
+    }
+    // In the case where a plugin is a path where no parent directory contains
+    // package.json, we can only classify it as local. Could happen if one puts a
+    // script in the parent directory of the site.
+    return { type: 'local' };
+}
+exports.getPluginVersion = getPluginVersion;
+/**
+ * We want all `@docusaurus/*` packages to have the exact same version!
+ * @see https://github.com/facebook/docusaurus/issues/3371
+ * @see https://github.com/facebook/docusaurus/pull/3386
+ */
+function checkDocusaurusPackagesVersion(siteMetadata) {
+    const { docusaurusVersion } = siteMetadata;
+    Object.entries(siteMetadata.pluginVersions).forEach(([plugin, versionInfo]) => {
+        if (versionInfo.type === 'package' &&
+            versionInfo.name?.startsWith('@docusaurus/') &&
+            versionInfo.version &&
+            versionInfo.version !== docusaurusVersion) {
+            // Should we throw instead? It still could work with different versions
+            logger_1.default.error `Invalid name=${plugin} version number=${versionInfo.version}.
+All official @docusaurus/* packages should have the exact same version as @docusaurus/core (number=${docusaurusVersion}).
+Maybe you want to check, or regenerate your yarn.lock or package-lock.json file?`;
+        }
+    });
+}
+async function loadSiteMetadata({ plugins, siteDir, }) {
+    const siteMetadata = {
+        docusaurusVersion: utils_1.DOCUSAURUS_VERSION,
+        siteVersion: await getPackageJsonVersion(path_1.default.join(siteDir, 'package.json')),
+        pluginVersions: Object.fromEntries(plugins
+            .filter(({ version: { type } }) => type !== 'synthetic')
+            .map(({ name, version }) => [name, version])),
+    };
+    checkDocusaurusPackagesVersion(siteMetadata);
+    return siteMetadata;
+}
+exports.loadSiteMetadata = loadSiteMetadata;

package/lib/server/translations/translations.d.ts

@@ -1,37 +1,31 @@
-import { InitPlugin } from '../plugins/init';
-import { TranslationFileContent, TranslationFile, TranslationMessage } from '@docusaurus/types';
+/**
+ * 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 { TranslationFileContent, TranslationFile, CodeTranslations, InitializedPlugin } from '@docusaurus/types';
 export declare type WriteTranslationsOptions = {
     override?: boolean;
     messagePrefix?: string;
 };
 declare type TranslationContext = {
-    siteDir: string;
-    locale: string;
+    localizationDir: string;
 };
-export declare function ensureTranslationFileContent(content: unknown): asserts content is TranslationFileContent;
-export declare function readTranslationFileContent(filePath: string): Promise<TranslationFileContent | undefined>;
-export declare function writeTranslationFileContent({ filePath, content: newContent, options, }: {
-    filePath: string;
-    content: TranslationFileContent;
-    options?: WriteTranslationsOptions;
-}): Promise<void>;
-export declare function getTranslationsDirPath(context: TranslationContext): string;
-export declare function getTranslationsLocaleDirPath(context: TranslationContext): string;
-export declare function getCodeTranslationsFilePath(context: TranslationContext): string;
 export declare function readCodeTranslationFileContent(context: TranslationContext): Promise<TranslationFileContent | undefined>;
 export declare function writeCodeTranslations(context: TranslationContext, content: TranslationFileContent, options: WriteTranslationsOptions): Promise<void>;
-export declare function writePluginTranslations({ siteDir, plugin, locale, translationFile, options, }: TranslationContext & {
-    plugin: InitPlugin;
+export declare function writePluginTranslations({ localizationDir, plugin, translationFile, options, }: TranslationContext & {
+    plugin: InitializedPlugin;
     translationFile: TranslationFile;
     options?: WriteTranslationsOptions;
 }): Promise<void>;
-export declare function localizePluginTranslationFile({ siteDir, plugin, locale, translationFile, }: TranslationContext & {
-    plugin: InitPlugin;
+export declare function localizePluginTranslationFile({ localizationDir, plugin, translationFile, }: TranslationContext & {
+    plugin: InitializedPlugin;
     translationFile: TranslationFile;
 }): Promise<TranslationFile>;
-export declare function getPluginsDefaultCodeTranslationMessages(plugins: InitPlugin[]): Promise<Record<string, string>>;
+export declare function getPluginsDefaultCodeTranslationMessages(plugins: InitializedPlugin[]): Promise<CodeTranslations>;
 export declare function applyDefaultCodeTranslations({ extractedCodeTranslations, defaultCodeMessages, }: {
-    extractedCodeTranslations: Record<string, TranslationMessage>;
-    defaultCodeMessages: Record<string, string>;
-}): Record<string, TranslationMessage>;
+    extractedCodeTranslations: TranslationFileContent;
+    defaultCodeMessages: CodeTranslations;
+}): TranslationFileContent;
 export {};