refactor: move PerfLogger from core to @docusaurus/logger (#10480)

packages/create-docusaurus/bin/index.js

@@ -10,7 +10,7 @@
 
 import path from 'path';
 import {createRequire} from 'module';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import semver from 'semver';
 import {program} from 'commander';
 

packages/create-docusaurus/src/index.ts

@@ -9,7 +9,7 @@ import fs from 'fs-extra';
 import {fileURLToPath} from 'url';
 import path from 'path';
 import _ from 'lodash';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import shell from 'shelljs';
 import prompts, {type Choice} from 'prompts';
 import supportsColor from 'supports-color';

packages/docusaurus-logger/src/index.ts

@@ -5,196 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import chalk from 'chalk';
+import OriginalLogger from './logger';
-import type {ReportingSeverity} from '@docusaurus/types';
 
-type InterpolatableValue = string | number | (string | number)[];
+export default OriginalLogger;
 
-const path = (msg: unknown): string => chalk.cyan.underline(`"${String(msg)}"`);
+// Extra named export to avoid problems in ESM modules
-const url = (msg: unknown): string => chalk.cyan.underline(msg);
+// Notably: core .mjs CLI + create-docusaurus
-const name = (msg: unknown): string => chalk.blue.bold(msg);
+// See https://github.com/facebook/docusaurus/pull/6661
-const code = (msg: unknown): string => chalk.cyan(`\`${String(msg)}\``);
+// See https://github.com/facebook/docusaurus/pull/7295
-const subdue = (msg: unknown): string => chalk.gray(msg);
+export const logger = OriginalLogger;
-const num = (msg: unknown): string => chalk.yellow(msg);
 
-function interpolate(
+export {PerfLogger} from './perfLogger';
-  msgs: TemplateStringsArray,
-  ...values: InterpolatableValue[]
-): string {
-  let res = '';
-  values.forEach((value, idx) => {
-    const flag = msgs[idx]!.match(/[a-z]+=$/);
-    res += msgs[idx]!.replace(/[a-z]+=$/, '');
-    const format = (() => {
-      if (!flag) {
-        return (a: string | number) => a;
-      }
-      switch (flag[0]) {
-        case 'path=':
-          return path;
-        case 'url=':
-          return url;
-        case 'number=':
-          return num;
-        case 'name=':
-          return name;
-        case 'subdue=':
-          return subdue;
-        case 'code=':
-          return code;
-        default:
-          throw new Error(
-            'Bad Docusaurus logging message. This is likely an internal bug, please report it.',
-          );
-      }
-    })();
-    res += Array.isArray(value)
-      ? `\n- ${value.map((v) => format(v)).join('\n- ')}`
-      : format(value);
-  });
-  res += msgs.slice(-1)[0];
-  return res;
-}
-
-function stringify(msg: unknown): string {
-  if (String(msg) === '[object Object]') {
-    return JSON.stringify(msg);
-  }
-  if (msg instanceof Date) {
-    return msg.toUTCString();
-  }
-  return String(msg);
-}
-
-function info(msg: unknown): void;
-function info(
-  msg: TemplateStringsArray,
-  ...values: [InterpolatableValue, ...InterpolatableValue[]]
-): void;
-function info(msg: unknown, ...values: InterpolatableValue[]): void {
-  console.info(
-    `${chalk.cyan.bold('[INFO]')} ${
-      values.length === 0
-        ? stringify(msg)
-        : interpolate(msg as TemplateStringsArray, ...values)
-    }`,
-  );
-}
-function warn(msg: unknown): void;
-function warn(
-  msg: TemplateStringsArray,
-  ...values: [InterpolatableValue, ...InterpolatableValue[]]
-): void;
-function warn(msg: unknown, ...values: InterpolatableValue[]): void {
-  console.warn(
-    chalk.yellow(
-      `${chalk.bold('[WARNING]')} ${
-        values.length === 0
-          ? stringify(msg)
-          : interpolate(msg as TemplateStringsArray, ...values)
-      }`,
-    ),
-  );
-}
-function error(msg: unknown): void;
-function error(
-  msg: TemplateStringsArray,
-  ...values: [InterpolatableValue, ...InterpolatableValue[]]
-): void;
-function error(msg: unknown, ...values: InterpolatableValue[]): void {
-  console.error(
-    chalk.red(
-      `${chalk.bold('[ERROR]')} ${
-        values.length === 0
-          ? stringify(msg)
-          : interpolate(msg as TemplateStringsArray, ...values)
-      }`,
-    ),
-  );
-}
-function success(msg: unknown): void;
-function success(
-  msg: TemplateStringsArray,
-  ...values: [InterpolatableValue, ...InterpolatableValue[]]
-): void;
-function success(msg: unknown, ...values: InterpolatableValue[]): void {
-  console.log(
-    `${chalk.green.bold('[SUCCESS]')} ${
-      values.length === 0
-        ? stringify(msg)
-        : interpolate(msg as TemplateStringsArray, ...values)
-    }`,
-  );
-}
-function throwError(msg: unknown): void;
-function throwError(
-  msg: TemplateStringsArray,
-  ...values: [InterpolatableValue, ...InterpolatableValue[]]
-): void;
-function throwError(msg: unknown, ...values: InterpolatableValue[]): void {
-  throw new Error(
-    values.length === 0
-      ? stringify(msg)
-      : interpolate(msg as TemplateStringsArray, ...values),
-  );
-}
-
-function newLine(): void {
-  console.log();
-}
-
-/**
- * Takes a message and reports it according to the severity that the user wants.
- *
- * - `ignore`: completely no-op
- * - `log`: uses the `INFO` log level
- * - `warn`: uses the `WARN` log level
- * - `throw`: aborts the process, throws the error.
- *
- * Since the logger doesn't have logging level filters yet, these severities
- * mostly just differ by their colors.
- *
- * @throws In addition to throwing when `reportingSeverity === "throw"`, this
- * function also throws if `reportingSeverity` is not one of the above.
- */
-function report(reportingSeverity: ReportingSeverity): typeof success {
-  const reportingMethods = {
-    ignore: () => {},
-    log: info,
-    warn,
-    throw: throwError,
-  };
-  if (
-    !Object.prototype.hasOwnProperty.call(reportingMethods, reportingSeverity)
-  ) {
-    throw new Error(
-      `Unexpected "reportingSeverity" value: ${reportingSeverity}.`,
-    );
-  }
-  return reportingMethods[reportingSeverity];
-}
-
-const logger = {
-  red: (msg: string | number): string => chalk.red(msg),
-  yellow: (msg: string | number): string => chalk.yellow(msg),
-  green: (msg: string | number): string => chalk.green(msg),
-  bold: (msg: string | number): string => chalk.bold(msg),
-  dim: (msg: string | number): string => chalk.dim(msg),
-  path,
-  url,
-  name,
-  code,
-  subdue,
-  num,
-  interpolate,
-  info,
-  warn,
-  error,
-  success,
-  report,
-  newLine,
-};
-
-// TODO remove when migrating to ESM
-// logger can only be default-imported in ESM with this
-export = logger;

packages/docusaurus-logger/src/logger.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 chalk from 'chalk';
+import type {ReportingSeverity} from '@docusaurus/types';
+
+type InterpolatableValue = string | number | (string | number)[];
+
+const path = (msg: unknown): string => chalk.cyan.underline(`"${String(msg)}"`);
+const url = (msg: unknown): string => chalk.cyan.underline(msg);
+const name = (msg: unknown): string => chalk.blue.bold(msg);
+const code = (msg: unknown): string => chalk.cyan(`\`${String(msg)}\``);
+const subdue = (msg: unknown): string => chalk.gray(msg);
+const num = (msg: unknown): string => chalk.yellow(msg);
+
+function interpolate(
+  msgs: TemplateStringsArray,
+  ...values: InterpolatableValue[]
+): string {
+  let res = '';
+  values.forEach((value, idx) => {
+    const flag = msgs[idx]!.match(/[a-z]+=$/);
+    res += msgs[idx]!.replace(/[a-z]+=$/, '');
+    const format = (() => {
+      if (!flag) {
+        return (a: string | number) => a;
+      }
+      switch (flag[0]) {
+        case 'path=':
+          return path;
+        case 'url=':
+          return url;
+        case 'number=':
+          return num;
+        case 'name=':
+          return name;
+        case 'subdue=':
+          return subdue;
+        case 'code=':
+          return code;
+        default:
+          throw new Error(
+            'Bad Docusaurus logging message. This is likely an internal bug, please report it.',
+          );
+      }
+    })();
+    res += Array.isArray(value)
+      ? `\n- ${value.map((v) => format(v)).join('\n- ')}`
+      : format(value);
+  });
+  res += msgs.slice(-1)[0];
+  return res;
+}
+
+function stringify(msg: unknown): string {
+  if (String(msg) === '[object Object]') {
+    return JSON.stringify(msg);
+  }
+  if (msg instanceof Date) {
+    return msg.toUTCString();
+  }
+  return String(msg);
+}
+
+function info(msg: unknown): void;
+function info(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function info(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.info(
+    `${chalk.cyan.bold('[INFO]')} ${
+      values.length === 0
+        ? stringify(msg)
+        : interpolate(msg as TemplateStringsArray, ...values)
+    }`,
+  );
+}
+function warn(msg: unknown): void;
+function warn(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function warn(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.warn(
+    chalk.yellow(
+      `${chalk.bold('[WARNING]')} ${
+        values.length === 0
+          ? stringify(msg)
+          : interpolate(msg as TemplateStringsArray, ...values)
+      }`,
+    ),
+  );
+}
+function error(msg: unknown): void;
+function error(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function error(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.error(
+    chalk.red(
+      `${chalk.bold('[ERROR]')} ${
+        values.length === 0
+          ? stringify(msg)
+          : interpolate(msg as TemplateStringsArray, ...values)
+      }`,
+    ),
+  );
+}
+function success(msg: unknown): void;
+function success(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function success(msg: unknown, ...values: InterpolatableValue[]): void {
+  console.log(
+    `${chalk.green.bold('[SUCCESS]')} ${
+      values.length === 0
+        ? stringify(msg)
+        : interpolate(msg as TemplateStringsArray, ...values)
+    }`,
+  );
+}
+function throwError(msg: unknown): void;
+function throwError(
+  msg: TemplateStringsArray,
+  ...values: [InterpolatableValue, ...InterpolatableValue[]]
+): void;
+function throwError(msg: unknown, ...values: InterpolatableValue[]): void {
+  throw new Error(
+    values.length === 0
+      ? stringify(msg)
+      : interpolate(msg as TemplateStringsArray, ...values),
+  );
+}
+
+function newLine(): void {
+  console.log();
+}
+
+/**
+ * Takes a message and reports it according to the severity that the user wants.
+ *
+ * - `ignore`: completely no-op
+ * - `log`: uses the `INFO` log level
+ * - `warn`: uses the `WARN` log level
+ * - `throw`: aborts the process, throws the error.
+ *
+ * Since the logger doesn't have logging level filters yet, these severities
+ * mostly just differ by their colors.
+ *
+ * @throws In addition to throwing when `reportingSeverity === "throw"`, this
+ * function also throws if `reportingSeverity` is not one of the above.
+ */
+function report(reportingSeverity: ReportingSeverity): typeof success {
+  const reportingMethods = {
+    ignore: () => {},
+    log: info,
+    warn,
+    throw: throwError,
+  };
+  if (
+    !Object.prototype.hasOwnProperty.call(reportingMethods, reportingSeverity)
+  ) {
+    throw new Error(
+      `Unexpected "reportingSeverity" value: ${reportingSeverity}.`,
+    );
+  }
+  return reportingMethods[reportingSeverity];
+}
+
+const logger = {
+  red: (msg: string | number): string => chalk.red(msg),
+  yellow: (msg: string | number): string => chalk.yellow(msg),
+  green: (msg: string | number): string => chalk.green(msg),
+  bold: (msg: string | number): string => chalk.bold(msg),
+  dim: (msg: string | number): string => chalk.dim(msg),
+  path,
+  url,
+  name,
+  code,
+  subdue,
+  num,
+  interpolate,
+  info,
+  warn,
+  error,
+  success,
+  report,
+  newLine,
+};
+
+export default logger;

packages/docusaurus-logger/src/perfLogger.ts

@@ -5,12 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 import {AsyncLocalStorage} from 'async_hooks';
-import logger from '@docusaurus/logger';
+import logger from './logger';
 
 // For now this is a private env variable we use internally
 // But we'll want to expose this feature officially some day
-export const PerfDebuggingEnabled: boolean =
+const PerfDebuggingEnabled: boolean = !!process.env.DOCUSAURUS_PERF_LOGGER;
-  !!process.env.DOCUSAURUS_PERF_LOGGER;
 
 const Thresholds = {
   min: 5,

packages/docusaurus-theme-translations/update.mjs

@@ -11,7 +11,7 @@ import path from 'path';
 import {fileURLToPath} from 'url';
 import fs from 'fs-extra';
 import _ from 'lodash';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import {getThemes, extractThemeCodeMessages} from './lib/utils.js';
 
 const LocalesDirPath = fileURLToPath(new URL('locales', import.meta.url));

packages/docusaurus/bin/beforeCli.mjs

@@ -11,7 +11,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import {createRequire} from 'module';
 import shell from 'shelljs';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import semver from 'semver';
 import updateNotifier from 'update-notifier';
 import boxen from 'boxen';

packages/docusaurus/bin/docusaurus.mjs

@@ -9,7 +9,7 @@
 // @ts-check
 
 import {inspect} from 'node:util';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 import cli from 'commander';
 import {DOCUSAURUS_VERSION} from '@docusaurus/utils';
 import {

packages/docusaurus/src/commands/build.ts

@@ -8,11 +8,10 @@
 import fs from 'fs-extra';
 import path from 'path';
 import _ from 'lodash';
-import logger from '@docusaurus/logger';
+import logger, {PerfLogger} from '@docusaurus/logger';
 import {DOCUSAURUS_VERSION, mapAsyncSequential} from '@docusaurus/utils';
 import {loadSite, loadContext, type LoadContextParams} from '../server/site';
 import {handleBrokenLinks} from '../server/brokenLinks';
-
 import {createBuildClientConfig} from '../webpack/client';
 import createServerConfig from '../webpack/server';
 import {
@@ -20,7 +19,6 @@ import {
   executePluginsConfigureWebpack,
 } from '../webpack/configure';
 import {compile} from '../webpack/utils';
-import {PerfLogger} from '../utils';
 
 import {loadI18n} from '../server/i18n';
 import {

packages/docusaurus/src/commands/start/utils.ts

@@ -9,9 +9,8 @@ import fs from 'fs-extra';
 import _ from 'lodash';
 import {prepareUrls} from 'react-dev-utils/WebpackDevServerUtils';
 import {normalizeUrl} from '@docusaurus/utils';
-import logger from '@docusaurus/logger';
+import logger, {PerfLogger} from '@docusaurus/logger';
 import {getHostPort} from '../../server/getHostPort';
-import {PerfLogger} from '../../utils';
 import {
   loadSite,
   type LoadSiteParams,

packages/docusaurus/src/server/plugins/plugins.ts

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {PerfLogger} from '@docusaurus/logger';
 import {initPlugins} from './init';
 import {createBootstrapPlugin, createMDXFallbackPlugin} from './synthetic';
 import {localizePluginTranslationFile} from '../translations/translations';
 import {sortRoutes} from './routeConfig';
-import {PerfLogger} from '../../utils';
 import {createPluginActionsUtils} from './actions';
 import {
   aggregateAllContent,

packages/docusaurus/src/server/site.ts

@@ -11,6 +11,7 @@ import {
   DEFAULT_BUILD_DIR_NAME,
   GENERATED_FILES_DIR_NAME,
 } from '@docusaurus/utils';
+import {PerfLogger} from '@docusaurus/logger';
 import combinePromises from 'combine-promises';
 import {loadSiteConfig} from './config';
 import {getAllClientModules} from './clientModules';
@@ -22,7 +23,6 @@ import {
   loadSiteCodeTranslations,
   getPluginsDefaultCodeTranslations,
 } from './translations/translations';
-import {PerfLogger} from '../utils';
 import {generateSiteFiles} from './codegen/codegen';
 import {getRoutesPaths, handleDuplicateRoutes} from './routes';
 import {createSiteStorage} from './storage';

packages/docusaurus/src/ssg.ts

@@ -12,8 +12,7 @@ import _ from 'lodash';
 import evaluate from 'eval';
 import pMap from 'p-map';
 import {minify} from 'html-minifier-terser';
-import logger from '@docusaurus/logger';
+import logger, {PerfLogger} from '@docusaurus/logger';
-import {PerfLogger} from './utils';
 import {renderSSRTemplate} from './templates/templates';
 import type {AppRenderer, AppRenderResult, SiteCollectedData} from './common';
 

website/_dogfooding/testSwizzleThemeClassic.mjs

@@ -8,7 +8,7 @@
 import path from 'path';
 import fs from 'fs-extra';
 import {fileURLToPath} from 'url';
-import logger from '@docusaurus/logger';
+import {logger} from '@docusaurus/logger';
 
 import classicTheme from '@docusaurus/theme-classic';