feat(v2): add --config option to CLI (#4308)

* feat: add --config & --generated-files-dir option to CLI

* revert --generated-files-dir option + some refactors

Co-authored-by: slorber <lorber.sebastien@gmail.com>

packages/docusaurus-types/src/index.d.ts

@@ -131,19 +131,25 @@ export type HostPortCLIOptions = {
   port?: string;
 };
 
-export type StartCLIOptions = HostPortCLIOptions & {
-  hotOnly: boolean;
-  open: boolean;
-  poll: boolean | number;
-  locale?: string;
+export type ConfigOptions = {
+  config: string;
 };
 
-export type ServeCLIOptions = HostPortCLIOptions & {
-  build: boolean;
-  dir: string;
-};
+export type StartCLIOptions = HostPortCLIOptions &
+  ConfigOptions & {
+    hotOnly: boolean;
+    open: boolean;
+    poll: boolean | number;
+    locale?: string;
+  };
+
+export type ServeCLIOptions = HostPortCLIOptions &
+  ConfigOptions & {
+    dir: string;
+    build: boolean;
+  };
 
-export type BuildOptions = {
+export type BuildOptions = ConfigOptions & {
   bundleAnalyzer: boolean;
   outDir: string;
   minify: boolean;
@@ -158,6 +164,7 @@ export interface LoadContext {
   siteDir: string;
   generatedFilesDir: string;
   siteConfig: DocusaurusConfig;
+  siteConfigPath: string;
   outDir: string;
   baseUrl: string;
   i18n: I18n;

packages/docusaurus/bin/docusaurus.js

@@ -109,6 +109,10 @@ cli
     '--out-dir <dir>',
     'The full path for the new output directory, relative to the current workspace (default: build).',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .option(
     '-l, --locale <locale>',
     'Build the site in a specified locale. Build all known locales otherwise.',
@@ -117,10 +121,11 @@ cli
     '--no-minify',
     'Build website without minimizing JS bundles (default: false)',
   )
-  .action((siteDir = '.', {bundleAnalyzer, outDir, locale, minify}) => {
+  .action((siteDir = '.', {bundleAnalyzer, config, outDir, locale, minify}) => {
     wrapCommand(build)(path.resolve(siteDir), {
       bundleAnalyzer,
       outDir,
+      config,
       locale,
       minify,
     });
@@ -155,12 +160,20 @@ cli
     '--out-dir <dir>',
     'The full path for the new output directory, relative to the current workspace (default: build).',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .option(
     '--skip-build',
     'Skip building website before deploy it (default: false)',
   )
-  .action((siteDir = '.', {outDir, skipBuild}) => {
-    wrapCommand(deploy)(path.resolve(siteDir), {outDir, skipBuild});
+  .action((siteDir = '.', {outDir, skipBuild, config}) => {
+    wrapCommand(deploy)(path.resolve(siteDir), {
+      outDir,
+      config,
+      skipBuild,
+    });
   });
 
 cli
@@ -173,21 +186,28 @@ cli
     '--hot-only',
     'Do not fallback to page refresh if hot reload fails (default: false)',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .option('--no-open', 'Do not open page in the browser (default: false)')
   .option(
     '--poll [interval]',
     'Use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds.',
   )
-  .action((siteDir = '.', {port, host, locale, hotOnly, open, poll}) => {
-    wrapCommand(start)(path.resolve(siteDir), {
-      port,
-      host,
-      locale,
-      hotOnly,
-      open,
-      poll,
-    });
-  });
+  .action(
+    (siteDir = '.', {port, host, locale, config, hotOnly, open, poll}) => {
+      wrapCommand(start)(path.resolve(siteDir), {
+        port,
+        host,
+        locale,
+        config,
+        hotOnly,
+        open,
+        poll,
+      });
+    },
+  );
 
 cli
   .command('serve [siteDir]')
@@ -196,6 +216,10 @@ cli
     '--dir <dir>',
     'The full path for the new output directory, relative to the current workspace (default: build).',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .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')
@@ -207,12 +231,14 @@ cli
         port = 3000,
         host = 'localhost',
         build: buildSite = false,
+        config,
       },
     ) => {
       wrapCommand(serve)(path.resolve(siteDir), {
         dir,
         port,
         build: buildSite,
+        config,
         host,
       });
     },
@@ -236,18 +262,23 @@ cli
     '--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.',
   )
+  .option(
+    '--config <config>',
+    'Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js`',
+  )
   .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.',
   )
   .action(
     (
       siteDir = '.',
-      {locale = undefined, override = false, messagePrefix = ''},
+      {locale = undefined, override = false, messagePrefix = '', config},
     ) => {
       wrapCommand(writeTranslations)(path.resolve(siteDir), {
         locale,
         override,
+        config,
         messagePrefix,
       });
     },

packages/docusaurus/src/commands/build.ts

@@ -14,7 +14,7 @@ import {Configuration, Plugin} from 'webpack';
 import {BundleAnalyzerPlugin} from 'webpack-bundle-analyzer';
 import merge from 'webpack-merge';
 import {STATIC_DIR_NAME} from '../constants';
-import {load} from '../server';
+import {load, loadContext} from '../server';
 import {handleBrokenLinks} from '../server/brokenLinks';
 
 import {BuildCLIOptions, Props} from '@docusaurus/types';
@@ -28,7 +28,6 @@ import {
 import CleanWebpackPlugin from '../webpack/plugins/CleanWebpackPlugin';
 import {loadI18n} from '../server/i18n';
 import {mapAsyncSequencial} from '@docusaurus/utils';
-import loadConfig from '../server/config';
 
 export default async function build(
   siteDir: string,
@@ -59,8 +58,13 @@ export default async function build(
       throw e;
     }
   }
-
-  const i18n = await loadI18n(loadConfig(siteDir), {
+  const context = await loadContext(siteDir, {
+    customOutDir: cliOptions.outDir,
+    customConfigFilePath: cliOptions.config,
+    locale: cliOptions.locale,
+    localizePath: cliOptions.locale ? false : undefined,
+  });
+  const i18n = await loadI18n(context.siteConfig, {
     locale: cliOptions.locale,
   });
   if (cliOptions.locale) {
@@ -112,6 +116,7 @@ async function buildLocale({
 
   const props: Props = await load(siteDir, {
     customOutDir: cliOptions.outDir,
+    customConfigFilePath: cliOptions.config,
     locale,
     localizePath: cliOptions.locale ? false : undefined,
   });

packages/docusaurus/src/commands/clear.ts

@@ -7,7 +7,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import chalk = require('chalk');
-import {BUILD_DIR_NAME, GENERATED_FILES_DIR_NAME} from '../constants';
+import {DEFAULT_BUILD_DIR_NAME, GENERATED_FILES_DIR_NAME} from '../constants';
 
 function removePath(fsPath: string) {
   return fs
@@ -24,7 +24,7 @@ function removePath(fsPath: string) {
 export default async function clear(siteDir: string): Promise<unknown> {
   return Promise.all([
     removePath(path.join(siteDir, GENERATED_FILES_DIR_NAME)),
-    removePath(path.join(siteDir, BUILD_DIR_NAME)),
+    removePath(path.join(siteDir, DEFAULT_BUILD_DIR_NAME)),
     removePath(path.join(siteDir, 'node_modules/.cache/cache-loader')),
   ]);
 }