refactor: convert CLI entry points to ESM; migrate create-docusaurus to ESM (#6661)

* refactor: convert CLI entry points to ESM

* fix

* fix

* fix

* fix!

* create-docusaurus ESM

* fix lock

* final touchups

* fix lodash

* fix

* use lodash

* fix hasYarn

packages/create-docusaurus/bin/index.js

@@ -8,12 +8,15 @@
 
 // @ts-check
 
-const logger = require('@docusaurus/logger').default;
-const semver = require('semver');
-const path = require('path');
-const {program} = require('commander');
-const {default: init} = require('../lib');
-const requiredVersion = require('../package.json').engines.node;
+import logger from '@docusaurus/logger';
+import semver from 'semver';
+import path from 'path';
+import {program} from 'commander';
+import {createRequire} from 'module';
+import init from '../lib/index.js';
+
+const packageJson = createRequire(import.meta.url)('../package.json');
+const requiredVersion = packageJson.engines.node;
 
 if (!semver.satisfies(process.version, requiredVersion)) {
   logger.error('Minimum Node.js version not met :(');
@@ -29,7 +32,7 @@ function wrapCommand(fn) {
     });
 }
 
-program.version(require('../package.json').version);
+program.version(packageJson.version);
 
 program
   .arguments('[siteName] [template] [rootDir]')

packages/create-docusaurus/package.json

@@ -2,6 +2,7 @@
   "name": "create-docusaurus",
   "version": "2.0.0-beta.15",
   "description": "Create Docusaurus apps easily.",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "https://github.com/facebook/docusaurus.git",
@@ -24,11 +25,11 @@
     "@docusaurus/logger": "2.0.0-beta.15",
     "commander": "^5.1.0",
     "fs-extra": "^10.0.0",
-    "lodash": "^4.17.20",
+    "lodash": "^4.17.21",
     "prompts": "^2.4.2",
     "semver": "^7.3.5",
     "shelljs": "^0.8.5",
-    "supports-color": "^8.1.1",
+    "supports-color": "^9.2.1",
     "tslib": "^2.3.1"
   },
   "engines": {

packages/create-docusaurus/src/index.ts

@@ -7,20 +7,19 @@
 
 import logger from '@docusaurus/logger';
 import fs from 'fs-extra';
-import {execSync} from 'child_process';
 import prompts, {type Choice} from 'prompts';
 import path from 'path';
 import shell from 'shelljs';
-import {kebabCase, sortBy} from 'lodash';
+import _ from 'lodash';
 import supportsColor from 'supports-color';
+import {fileURLToPath} from 'url';
 
 const RecommendedTemplate = 'classic';
 const TypeScriptTemplateSuffix = '-typescript';
 
 function hasYarn() {
   try {
-    execSync('yarnpkg --version', {stdio: 'ignore'});
-    return true;
+    return shell.exec('yarnpkg --version', {silent: true}).code === 0;
   } catch (e) {
     return false;
   }
@@ -50,7 +49,7 @@ function readTemplates(templatesDir: string) {
     );
 
   // Classic should be first in list!
-  return sortBy(templates, (t) => t !== RecommendedTemplate);
+  return _.sortBy(templates, (t) => t !== RecommendedTemplate);
 }
 
 function createTemplateChoices(templates: string[]) {
@@ -135,7 +134,7 @@ export default async function init(
   }> = {},
 ): Promise<void> {
   const useYarn = cliOptions.useNpm ? false : hasYarn();
-  const templatesDir = path.resolve(__dirname, '../templates');
+  const templatesDir = fileURLToPath(new URL('../templates', import.meta.url));
   const templates = readTemplates(templatesDir);
   const hasTS = (templateName: string) =>
     fs.pathExistsSync(
@@ -296,7 +295,7 @@ export default async function init(
   // Update package.json info.
   try {
     await updatePkg(path.join(dest, 'package.json'), {
-      name: kebabCase(name),
+      name: _.kebabCase(name),
       version: '0.0.0',
       private: true,
     });

packages/create-docusaurus/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "module": "es2020",
     "incremental": true,
     "tsBuildInfoFile": "./lib/.tsbuildinfo",
     "rootDir": "src",

packages/docusaurus-logger/src/index.ts

@@ -138,4 +138,9 @@ const logger = {
   success,
 };
 
+// TODO remove when migrating to ESM
+// logger can only be default-imported in ESM with this
+module.exports = logger;
+module.exports.default = logger;
+
 export default logger;

packages/docusaurus-migrate/bin/index.js

@@ -8,14 +8,15 @@
 
 // @ts-check
 
-const logger = require('@docusaurus/logger').default;
-const semver = require('semver');
-const cli = require('commander');
-const path = require('path');
+import logger from '@docusaurus/logger';
+import semver from 'semver';
+import cli from 'commander';
+import path from 'path';
+import {createRequire} from 'module';
+import {migrateDocusaurusProject, migrateMDToMDX} from '../lib/index.js';
 
-const requiredVersion = require('../package.json').engines.node;
-
-const {migrateDocusaurusProject, migrateMDToMDX} = require('../lib');
+const requiredVersion = createRequire(import.meta.url)('../package.json')
+  .engines.node;
 
 function wrapCommand(fn) {
   return (...args) =>
@@ -50,6 +51,7 @@ cli
     const newSitePath = path.resolve(newDir);
     wrapCommand(migrateMDToMDX)(sitePath, newSitePath);
   });
+
 cli.parse(process.argv);
 
 if (!process.argv.slice(2).length) {

packages/docusaurus-migrate/package.json

@@ -20,7 +20,7 @@
     "access": "public"
   },
   "bin": {
-    "docusaurus-migrate": "bin/index.js"
+    "docusaurus-migrate": "bin/index.mjs"
   },
   "dependencies": {
     "@babel/preset-env": "^7.16.11",

packages/docusaurus/bin/beforeCli.mjs

@@ -7,21 +7,24 @@
 
 // @ts-check
 
-const logger = require('@docusaurus/logger').default;
-const fs = require('fs-extra');
-const semver = require('semver');
-const path = require('path');
-const updateNotifier = require('update-notifier');
-const boxen = require('boxen');
+import logger from '@docusaurus/logger';
+import fs from 'fs-extra';
+import semver from 'semver';
+import path from 'path';
+import updateNotifier from 'update-notifier';
+import boxen from 'boxen';
+import {createRequire} from 'module';
+
+const packageJson = createRequire(import.meta.url)('../package.json');
+const sitePkg = createRequire(path.join(process.cwd(), 'package.json'))(
+  './package.json',
+);
 
 const {
   name,
   version,
   engines: {node: requiredVersion},
-} = require('../package.json');
-
-// eslint-disable-next-line import/no-dynamic-require
-const sitePkg = require(path.resolve(process.cwd(), 'package.json'));
+} = packageJson;
 
 /**
  * Notify user if `@docusaurus` packages are outdated
@@ -130,4 +133,4 @@ function beforeCli() {
   }
 }
 
-module.exports = beforeCli;
+export default beforeCli;

packages/docusaurus/bin/docusaurus.mjs

@@ -8,10 +8,11 @@
 
 // @ts-check
 
-const logger = require('@docusaurus/logger').default;
-const fs = require('fs');
-const cli = require('commander');
-const {
+import logger from '@docusaurus/logger';
+import fs from 'fs';
+import cli from 'commander';
+import {createRequire} from 'module';
+import {
   build,
   swizzle,
   deploy,
@@ -21,15 +22,16 @@ const {
   clear,
   writeTranslations,
   writeHeadingIds,
-} = require('../lib');
-
-const beforeCli = require('./beforeCli');
+} from '../lib/index.js';
+import beforeCli from './beforeCli.mjs';
 
 beforeCli();
 
 const resolveDir = (dir = '.') => fs.realpathSync(dir);
 
-cli.version(require('../package.json').version).usage('<command> [options]');
+cli
+  .version(createRequire(import.meta.url)('../package.json').version)
+  .usage('<command> [options]');
 
 cli
   .command('build [siteDir]')
@@ -226,6 +228,9 @@ cli.arguments('<command>').action((cmd) => {
   logger.error`    Unknown command name=${cmd}.`;
 });
 
+/**
+ * @param {string} command
+ */
 function isInternalCommand(command) {
   return [
     'start',

packages/docusaurus/package.json

@@ -21,7 +21,7 @@
     "directory": "packages/docusaurus"
   },
   "bin": {
-    "docusaurus": "bin/docusaurus.js"
+    "docusaurus": "bin/docusaurus.mjs"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.client.json && node copyUntypedFiles.mjs",

packages/docusaurus/src/index.ts

@@ -5,12 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export {default as build} from './commands/build';
-export {default as start} from './commands/start';
-export {default as swizzle} from './commands/swizzle';
-export {default as deploy} from './commands/deploy';
-export {default as externalCommand} from './commands/external';
-export {default as serve} from './commands/serve';
-export {default as clear} from './commands/clear';
-export {default as writeTranslations} from './commands/writeTranslations';
-export {default as writeHeadingIds} from './commands/writeHeadingIds';
+import build from './commands/build';
+import clear from './commands/clear';
+import deploy from './commands/deploy';
+import externalCommand from './commands/external';
+import serve from './commands/serve';
+import start from './commands/start';
+import swizzle from './commands/swizzle';
+import writeHeadingIds from './commands/writeHeadingIds';
+import writeTranslations from './commands/writeTranslations';
+
+export {
+  build,
+  clear,
+  deploy,
+  externalCommand,
+  serve,
+  start,
+  swizzle,
+  writeHeadingIds,
+  writeTranslations,
+};

yarn.lock

@@ -17761,7 +17761,7 @@ supports-color@^7.0.0, supports-color@^7.1.0:
   dependencies:
     has-flag "^4.0.0"
 
-supports-color@^8.0.0, supports-color@^8.1.0, supports-color@^8.1.1:
+supports-color@^8.0.0, supports-color@^8.1.0:
   version "8.1.1"
   resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-8.1.1.tgz#cd6fc17e28500cff56c1b86c0a7fd4a54a73005c"
   integrity sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==