@docusaurus/core 0.0.0-5858 → 0.0.0-5861

package/lib/server/site.js

@@ -0,0 +1,167 @@
+"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.reloadSitePlugin = exports.reloadSite = exports.loadSite = exports.loadContext = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+const config_1 = require("./config");
+const clientModules_1 = require("./clientModules");
+const plugins_1 = require("./plugins/plugins");
+const htmlTags_1 = require("./htmlTags");
+const siteMetadata_1 = require("./siteMetadata");
+const i18n_1 = require("./i18n");
+const translations_1 = require("./translations/translations");
+const utils_2 = require("../utils");
+const codegen_1 = require("./codegen/codegen");
+const routes_1 = require("./routes");
+/**
+ * Loading context is the very first step in site building. Its params are
+ * directly acquired from CLI options. It mainly loads `siteConfig` and the i18n
+ * context (which includes code translations). The `LoadContext` will be passed
+ * to plugin constructors.
+ */
+async function loadContext(params) {
+    const { siteDir, outDir: baseOutDir = utils_1.DEFAULT_BUILD_DIR_NAME, locale, config: customConfigFilePath, } = params;
+    const generatedFilesDir = path_1.default.resolve(siteDir, utils_1.GENERATED_FILES_DIR_NAME);
+    const { siteConfig: initialSiteConfig, siteConfigPath } = await (0, config_1.loadSiteConfig)({
+        siteDir,
+        customConfigFilePath,
+    });
+    const i18n = await (0, i18n_1.loadI18n)(initialSiteConfig, { locale });
+    const baseUrl = (0, utils_1.localizePath)({
+        path: initialSiteConfig.baseUrl,
+        i18n,
+        options: params,
+        pathType: 'url',
+    });
+    const outDir = (0, utils_1.localizePath)({
+        path: path_1.default.resolve(siteDir, baseOutDir),
+        i18n,
+        options: params,
+        pathType: 'fs',
+    });
+    const localizationDir = path_1.default.resolve(siteDir, i18n.path, i18n.localeConfigs[i18n.currentLocale].path);
+    const siteConfig = { ...initialSiteConfig, baseUrl };
+    const codeTranslations = await (0, translations_1.loadSiteCodeTranslations)({ localizationDir });
+    return {
+        siteDir,
+        generatedFilesDir,
+        localizationDir,
+        siteConfig,
+        siteConfigPath,
+        outDir,
+        baseUrl,
+        i18n,
+        codeTranslations,
+    };
+}
+exports.loadContext = loadContext;
+async function createSiteProps(params) {
+    const { plugins, routes, context } = params;
+    const { generatedFilesDir, siteDir, siteConfig, siteConfigPath, outDir, baseUrl, i18n, localizationDir, codeTranslations: siteCodeTranslations, } = context;
+    const { headTags, preBodyTags, postBodyTags } = (0, htmlTags_1.loadHtmlTags)(plugins);
+    const { codeTranslations, siteMetadata } = await (0, combine_promises_1.default)({
+        // TODO code translations should be loaded as part of LoadedPlugin?
+        codeTranslations: utils_2.PerfLogger.async('Load - loadCodeTranslations', async () => ({
+            ...(await (0, translations_1.getPluginsDefaultCodeTranslationMessages)(plugins)),
+            ...siteCodeTranslations,
+        })),
+        siteMetadata: utils_2.PerfLogger.async('Load - loadSiteMetadata', () => (0, siteMetadata_1.loadSiteMetadata)({ plugins, siteDir })),
+    });
+    (0, routes_1.handleDuplicateRoutes)(routes, siteConfig.onDuplicateRoutes);
+    const routesPaths = (0, routes_1.getRoutesPaths)(routes, baseUrl);
+    return {
+        siteConfig,
+        siteConfigPath,
+        siteMetadata,
+        siteDir,
+        outDir,
+        baseUrl,
+        i18n,
+        localizationDir,
+        generatedFilesDir,
+        routes,
+        routesPaths,
+        plugins,
+        headTags,
+        preBodyTags,
+        postBodyTags,
+        codeTranslations,
+    };
+}
+// TODO global data should be part of site props?
+async function createSiteFiles({ site, globalData, }) {
+    return utils_2.PerfLogger.async('Load - createSiteFiles', async () => {
+        const { props: { plugins, generatedFilesDir, siteConfig, siteMetadata, i18n, codeTranslations, routes, baseUrl, }, } = site;
+        const clientModules = (0, clientModules_1.loadClientModules)(plugins);
+        await (0, codegen_1.generateSiteFiles)({
+            generatedFilesDir,
+            clientModules,
+            siteConfig,
+            siteMetadata,
+            i18n,
+            codeTranslations,
+            globalData,
+            routes,
+            baseUrl,
+        });
+    });
+}
+/**
+ * This is the crux of the Docusaurus server-side. It reads everything it needs—
+ * code translations, config file, plugin modules... Plugins then use their
+ * lifecycles to generate content and other data. It is side-effect-ful because
+ * it generates temp files in the `.docusaurus` folder for the bundler.
+ */
+async function loadSite(params) {
+    utils_2.PerfLogger.start('Load - loadContext');
+    const context = await loadContext(params);
+    utils_2.PerfLogger.end('Load - loadContext');
+    utils_2.PerfLogger.start('Load - loadPlugins');
+    const { plugins, routes, globalData } = await (0, plugins_1.loadPlugins)(context);
+    utils_2.PerfLogger.end('Load - loadPlugins');
+    const props = await createSiteProps({ plugins, routes, globalData, context });
+    const site = { props, params };
+    await createSiteFiles({
+        site,
+        globalData,
+    });
+    return site;
+}
+exports.loadSite = loadSite;
+async function reloadSite(site) {
+    // TODO this can be optimized, for example:
+    //  - plugins loading same data as before should not recreate routes/bundles
+    //  - codegen does not need to re-run if nothing changed
+    return loadSite(site.params);
+}
+exports.reloadSite = reloadSite;
+async function reloadSitePlugin(site, pluginIdentifier) {
+    console.log(`reloadSitePlugin ${pluginIdentifier.name}@${pluginIdentifier.id}`);
+    const { plugins, routes, globalData } = await (0, plugins_1.reloadPlugin)({
+        pluginIdentifier,
+        plugins: site.props.plugins,
+        context: site.props,
+    });
+    const newProps = await createSiteProps({
+        plugins,
+        routes,
+        globalData,
+        context: site.props, // Props extends Context
+    });
+    const newSite = {
+        props: newProps,
+        params: site.params,
+    };
+    // TODO optimize, bypass useless codegen if new site is similar to old site
+    await createSiteFiles({ site: newSite, globalData });
+    return newSite;
+}
+exports.reloadSitePlugin = reloadSitePlugin;

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

@@ -28,4 +28,7 @@ export declare function applyDefaultCodeTranslations({ extractedCodeTranslations
     extractedCodeTranslations: TranslationFileContent;
     defaultCodeMessages: CodeTranslations;
 }): TranslationFileContent;
+export declare function loadSiteCodeTranslations({ localizationDir, }: {
+    localizationDir: string;
+}): Promise<CodeTranslations>;
 export {};

package/lib/server/translations/translations.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyDefaultCodeTranslations = exports.getPluginsDefaultCodeTranslationMessages = exports.localizePluginTranslationFile = exports.writePluginTranslations = exports.writeCodeTranslations = exports.readCodeTranslationFileContent = void 0;
+exports.loadSiteCodeTranslations = exports.applyDefaultCodeTranslations = exports.getPluginsDefaultCodeTranslationMessages = exports.localizePluginTranslationFile = exports.writePluginTranslations = exports.writeCodeTranslations = exports.readCodeTranslationFileContent = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
@@ -162,3 +162,9 @@ Please report this Docusaurus issue. name=${unusedDefaultCodeMessages}`;
     }));
 }
 exports.applyDefaultCodeTranslations = applyDefaultCodeTranslations;
+async function loadSiteCodeTranslations({ localizationDir, }) {
+    const codeTranslationFileContent = (await readCodeTranslationFileContent({ localizationDir })) ?? {};
+    // We only need key->message for code translations
+    return lodash_1.default.mapValues(codeTranslationFileContent, (value) => value.message);
+}
+exports.loadSiteCodeTranslations = loadSiteCodeTranslations;

package/lib/server/utils.d.ts

@@ -5,6 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Globby } from '@docusaurus/utils';
-import type { RouteConfig } from '@docusaurus/types';
-export declare function getAllFinalRoutes(routeConfig: RouteConfig[]): RouteConfig[];
 export declare function safeGlobby(patterns: string[], options?: Globby.GlobbyOptions): Promise<string[]>;

package/lib/server/utils.js

@@ -6,18 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.safeGlobby = exports.getAllFinalRoutes = void 0;
+exports.safeGlobby = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
-// Recursively get the final routes (routes with no subroutes)
-function getAllFinalRoutes(routeConfig) {
-    function getFinalRoutes(route) {
-        return route.routes ? route.routes.flatMap(getFinalRoutes) : [route];
-    }
-    return routeConfig.flatMap(getFinalRoutes);
-}
-exports.getAllFinalRoutes = getAllFinalRoutes;
 // Globby that fix Windows path patterns
 // See https://github.com/facebook/docusaurus/pull/4222#issuecomment-795517329
 async function safeGlobby(patterns, options) {

package/lib/utils.d.ts

@@ -3,6 +3,7 @@ type PerfLoggerAPI = {
     start: (label: string) => void;
     end: (label: string) => void;
     log: (message: string) => void;
+    async: <Result>(label: string, asyncFn: () => Result | Promise<Result>) => Promise<Result>;
 };
 export declare const PerfLogger: PerfLoggerAPI;
 export {};

package/lib/utils.js

@@ -19,13 +19,24 @@ function createPerfLogger() {
             start: noop,
             end: noop,
             log: noop,
+            async: async (_label, asyncFn) => asyncFn(),
         };
     }
     const prefix = logger_1.default.yellow(`[PERF] `);
+    const start = (label) => console.time(prefix + label);
+    const end = (label) => console.timeEnd(prefix + label);
+    const log = (label) => console.log(prefix + label);
+    const async = async (label, asyncFn) => {
+        start(label);
+        const result = await asyncFn();
+        end(label);
+        return result;
+    };
     return {
-        start: (label) => console.time(prefix + label),
-        end: (label) => console.timeEnd(prefix + label),
-        log: (label) => console.log(prefix + label),
+        start,
+        end,
+        log,
+        async,
     };
 }
 exports.PerfLogger = createPerfLogger();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "0.0.0-5858",
+  "version": "0.0.0-5861",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -43,13 +43,13 @@
     "@babel/runtime": "^7.22.6",
     "@babel/runtime-corejs3": "^7.22.6",
     "@babel/traverse": "^7.22.8",
-    "@docusaurus/cssnano-preset": "0.0.0-5858",
-    "@docusaurus/logger": "0.0.0-5858",
-    "@docusaurus/mdx-loader": "0.0.0-5858",
+    "@docusaurus/cssnano-preset": "0.0.0-5861",
+    "@docusaurus/logger": "0.0.0-5861",
+    "@docusaurus/mdx-loader": "0.0.0-5861",
     "@docusaurus/react-loadable": "5.5.2",
-    "@docusaurus/utils": "0.0.0-5858",
-    "@docusaurus/utils-common": "0.0.0-5858",
-    "@docusaurus/utils-validation": "0.0.0-5858",
+    "@docusaurus/utils": "0.0.0-5861",
+    "@docusaurus/utils-common": "0.0.0-5861",
+    "@docusaurus/utils-validation": "0.0.0-5861",
     "@svgr/webpack": "^6.5.1",
     "autoprefixer": "^10.4.14",
     "babel-loader": "^9.1.3",
@@ -105,8 +105,9 @@
     "webpackbar": "^5.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-5858",
-    "@docusaurus/types": "0.0.0-5858",
+    "@docusaurus/module-type-aliases": "0.0.0-5861",
+    "@docusaurus/types": "0.0.0-5861",
+    "@total-typescript/shoehorn": "^0.1.2",
     "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^18.2.7",
     "@types/react-router-config": "^5.0.7",
@@ -125,5 +126,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "03c831aae7cfffd88cb38425971139a865a79a40"
+  "gitHead": "f6dfa0af9be06d1e24f30243244145fdc03fb25c"
 }

package/lib/commands/start.js

@@ -1,242 +0,0 @@
-"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.start = 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 lodash_1 = tslib_1.__importDefault(require("lodash"));
-const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
-const utils_1 = require("@docusaurus/utils");
-const chokidar_1 = tslib_1.__importDefault(require("chokidar"));
-const openBrowser_1 = tslib_1.__importDefault(require("react-dev-utils/openBrowser"));
-const WebpackDevServerUtils_1 = require("react-dev-utils/WebpackDevServerUtils");
-const evalSourceMapMiddleware_1 = tslib_1.__importDefault(require("react-dev-utils/evalSourceMapMiddleware"));
-const webpack_1 = tslib_1.__importDefault(require("webpack"));
-const webpack_dev_server_1 = tslib_1.__importDefault(require("webpack-dev-server"));
-const webpack_merge_1 = tslib_1.__importDefault(require("webpack-merge"));
-const server_1 = require("../server");
-const client_1 = require("../webpack/client");
-const utils_2 = require("../webpack/utils");
-const getHostPort_1 = require("../server/getHostPort");
-const utils_3 = require("../utils");
-async function start(siteDirParam = '.', cliOptions = {}) {
-    // Temporary workaround to unlock the ability to translate the site config
-    // We'll remove it if a better official API can be designed
-    // See https://github.com/facebook/docusaurus/issues/4542
-    process.env.DOCUSAURUS_CURRENT_LOCALE = cliOptions.locale;
-    const siteDir = await fs_extra_1.default.realpath(siteDirParam);
-    logger_1.default.info('Starting the development server...');
-    async function loadSite() {
-        utils_3.PerfLogger.start('Loading site');
-        const result = await (0, server_1.load)({
-            siteDir,
-            config: cliOptions.config,
-            locale: cliOptions.locale,
-            localizePath: undefined, // Should this be configurable?
-        });
-        utils_3.PerfLogger.end('Loading site');
-        return result;
-    }
-    // Process all related files as a prop.
-    const props = await loadSite();
-    const { host, port, getOpenUrl } = await createUrlUtils({ cliOptions });
-    const openUrl = getOpenUrl({ baseUrl: props.baseUrl });
-    logger_1.default.success `Docusaurus website is running at: url=${openUrl}`;
-    // Reload files processing.
-    const reload = lodash_1.default.debounce(() => {
-        loadSite()
-            .then(({ baseUrl: newBaseUrl }) => {
-            const newOpenUrl = getOpenUrl({ baseUrl: newBaseUrl });
-            if (newOpenUrl !== openUrl) {
-                logger_1.default.success `Docusaurus website is running at: url=${newOpenUrl}`;
-            }
-        })
-            .catch((err) => {
-            logger_1.default.error(err.stack);
-        });
-    }, 500);
-    // TODO this is historically not optimized!
-    //  When any site file changes, we reload absolutely everything :/
-    //  At least we should try to reload only one plugin individually?
-    setupFileWatchers({
-        props,
-        cliOptions,
-        onFileChange: () => {
-            reload();
-        },
-    });
-    const config = await getStartClientConfig({
-        props,
-        minify: cliOptions.minify ?? true,
-        poll: cliOptions.poll,
-    });
-    const compiler = (0, webpack_1.default)(config);
-    registerE2ETestHook(compiler);
-    const defaultDevServerConfig = await createDevServerConfig({
-        cliOptions,
-        props,
-        host,
-        port,
-    });
-    // Allow plugin authors to customize/override devServer config
-    const devServerConfig = (0, webpack_merge_1.default)([defaultDevServerConfig, config.devServer].filter(Boolean));
-    const devServer = new webpack_dev_server_1.default(devServerConfig, compiler);
-    devServer.startCallback(() => {
-        if (cliOptions.open) {
-            (0, openBrowser_1.default)(openUrl);
-        }
-    });
-    ['SIGINT', 'SIGTERM'].forEach((sig) => {
-        process.on(sig, () => {
-            devServer.stop();
-            process.exit();
-        });
-    });
-}
-exports.start = start;
-function createPollingOptions({ cliOptions }) {
-    return {
-        usePolling: !!cliOptions.poll,
-        interval: Number.isInteger(cliOptions.poll)
-            ? cliOptions.poll
-            : undefined,
-    };
-}
-function setupFileWatchers({ props, cliOptions, onFileChange, }) {
-    const { siteDir } = props;
-    const pathsToWatch = getPathsToWatch({ props });
-    const pollingOptions = createPollingOptions({ cliOptions });
-    const fsWatcher = chokidar_1.default.watch(pathsToWatch, {
-        cwd: siteDir,
-        ignoreInitial: true,
-        ...{ pollingOptions },
-    });
-    ['add', 'change', 'unlink', 'addDir', 'unlinkDir'].forEach((event) => fsWatcher.on(event, onFileChange));
-}
-function getPathsToWatch({ props }) {
-    const { siteDir, siteConfigPath, plugins, localizationDir } = props;
-    const normalizeToSiteDir = (filepath) => {
-        if (filepath && path_1.default.isAbsolute(filepath)) {
-            return (0, utils_1.posixPath)(path_1.default.relative(siteDir, filepath));
-        }
-        return (0, utils_1.posixPath)(filepath);
-    };
-    const pluginsPaths = plugins
-        .flatMap((plugin) => plugin.getPathsToWatch?.() ?? [])
-        .filter(Boolean)
-        .map(normalizeToSiteDir);
-    return [...pluginsPaths, siteConfigPath, localizationDir];
-}
-async function createUrlUtils({ cliOptions }) {
-    const protocol = process.env.HTTPS === 'true' ? 'https' : 'http';
-    const { host, port } = await (0, getHostPort_1.getHostPort)(cliOptions);
-    if (port === null) {
-        return process.exit();
-    }
-    const getOpenUrl = ({ baseUrl }) => {
-        const urls = (0, WebpackDevServerUtils_1.prepareUrls)(protocol, host, port);
-        return (0, utils_1.normalizeUrl)([urls.localUrlForBrowser, baseUrl]);
-    };
-    return { host, port, getOpenUrl };
-}
-async function createDevServerConfig({ cliOptions, props, host, port, }) {
-    const { baseUrl, siteDir, siteConfig } = props;
-    const pollingOptions = createPollingOptions({ cliOptions });
-    const httpsConfig = await (0, utils_2.getHttpsConfig)();
-    // https://webpack.js.org/configuration/dev-server
-    return {
-        hot: cliOptions.hotOnly ? 'only' : true,
-        liveReload: false,
-        client: {
-            progress: true,
-            overlay: {
-                warnings: false,
-                errors: true,
-            },
-            webSocketURL: {
-                hostname: '0.0.0.0',
-                port: 0,
-            },
-        },
-        headers: {
-            'access-control-allow-origin': '*',
-        },
-        devMiddleware: {
-            publicPath: baseUrl,
-            // Reduce log verbosity, see https://github.com/facebook/docusaurus/pull/5420#issuecomment-906613105
-            stats: 'summary',
-        },
-        static: siteConfig.staticDirectories.map((dir) => ({
-            publicPath: baseUrl,
-            directory: path_1.default.resolve(siteDir, dir),
-            watch: {
-                // Useful options for our own monorepo using symlinks!
-                // See https://github.com/webpack/webpack/issues/11612#issuecomment-879259806
-                followSymlinks: true,
-                ignored: /node_modules\/(?!@docusaurus)/,
-                ...{ pollingOptions },
-            },
-        })),
-        ...(httpsConfig && {
-            server: typeof httpsConfig === 'object'
-                ? {
-                    type: 'https',
-                    options: httpsConfig,
-                }
-                : 'https',
-        }),
-        historyApiFallback: {
-            rewrites: [{ from: /\/*/, to: baseUrl }],
-        },
-        allowedHosts: 'all',
-        host,
-        port,
-        setupMiddlewares: (middlewares, devServer) => {
-            // This lets us fetch source contents from webpack for the error overlay.
-            middlewares.unshift((0, evalSourceMapMiddleware_1.default)(devServer));
-            return middlewares;
-        },
-    };
-}
-// E2E_TEST=true docusaurus start
-// Makes "docusaurus start" exit immediately on success/error, for E2E test
-function registerE2ETestHook(compiler) {
-    compiler.hooks.done.tap('done', (stats) => {
-        const errorsWarnings = stats.toJson('errors-warnings');
-        const statsErrorMessage = (0, utils_2.formatStatsErrorMessage)(errorsWarnings);
-        if (statsErrorMessage) {
-            console.error(statsErrorMessage);
-        }
-        (0, utils_2.printStatsWarnings)(errorsWarnings);
-        if (process.env.E2E_TEST) {
-            if (stats.hasErrors()) {
-                logger_1.default.error('E2E_TEST: Project has compiler errors.');
-                process.exit(1);
-            }
-            logger_1.default.success('E2E_TEST: Project can compile.');
-            process.exit(0);
-        }
-    });
-}
-async function getStartClientConfig({ props, minify, poll, }) {
-    const { plugins, siteConfig } = props;
-    let { clientConfig: config } = await (0, client_1.createStartClientConfig)({
-        props,
-        minify,
-        poll,
-    });
-    config = (0, utils_2.executePluginsConfigurePostCss)({ plugins, config });
-    config = (0, utils_2.executePluginsConfigureWebpack)({
-        plugins,
-        config,
-        isServer: false,
-        jsLoader: siteConfig.webpack?.jsLoader,
-    });
-    return config;
-}