refactor(cli): normalize the application of default option values (#7220)

* refactor(cli): normalize default value application

* improve help text

packages/docusaurus/bin/docusaurus.mjs

@@ -54,14 +54,8 @@ cli
     '--no-minify',
     'build website without minimizing JS bundles (default: false)',
   )
-  .action(async (siteDir, {bundleAnalyzer, config, outDir, locale, minify}) => {
-    build(await resolveDir(siteDir), {
-      bundleAnalyzer,
-      outDir,
-      config,
-      locale,
-      minify,
-    });
+  .action(async (siteDir, options) => {
+    build(await resolveDir(siteDir), options);
   });
 
 cli
@@ -86,9 +80,9 @@ cli
     'copy TypeScript theme files when possible (default: false)',
   )
   .option('--danger', 'enable swizzle for unsafe component of themes')
-  .action(async (themeName, componentName, siteDir, options) => {
-    swizzle(await resolveDir(siteDir), themeName, componentName, options);
-  });
+  .action(async (themeName, componentName, siteDir, options) =>
+    swizzle(await resolveDir(siteDir), themeName, componentName, options),
+  );
 
 cli
   .command('deploy [siteDir]')
@@ -109,13 +103,9 @@ cli
     '--skip-build',
     'skip building website before deploy it (default: false)',
   )
-  .action(async (siteDir, {outDir, skipBuild, config}) => {
-    deploy(await resolveDir(siteDir), {
-      outDir,
-      config,
-      skipBuild,
-    });
-  });
+  .action(async (siteDir, options) =>
+    deploy(await resolveDir(siteDir), options),
+  );
 
 cli
   .command('start [siteDir]')
@@ -136,18 +126,8 @@ cli
     '--poll [interval]',
     'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds',
   )
-  .action(
-    async (siteDir, {port, host, locale, config, hotOnly, open, poll}) => {
-      start(await resolveDir(siteDir), {
-        port,
-        host,
-        locale,
-        config,
-        hotOnly,
-        open,
-        poll,
-      });
-    },
+  .action(async (siteDir, options) =>
+    start(await resolveDir(siteDir), options),
   );
 
 cli
@@ -164,44 +144,25 @@ cli
   .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)')
-  .action(
-    async (
-      siteDir,
-      {
-        dir = 'build',
-        port = 3000,
-        host = 'localhost',
-        build: buildSite = false,
-        config,
-      },
-    ) => {
-      serve(await resolveDir(siteDir), {
-        dir,
-        port,
-        build: buildSite,
-        config,
-        host,
-      });
-    },
+  .action(async (siteDir, options) =>
+    serve(await resolveDir(siteDir), options),
   );
 
 cli
   .command('clear [siteDir]')
   .description('Remove build artifacts.')
-  .action(async (siteDir) => {
-    clear(await resolveDir(siteDir));
-  });
+  .action(async (siteDir) => clear(await resolveDir(siteDir)));
 
 cli
   .command('write-translations [siteDir]')
   .description('Extract required translations of your site.')
   .option(
     '-l, --locale <locale>',
-    'the locale folder to write the translations\n"--locale fr" will write translations in ./i18n/fr folder)',
+    'the locale folder to write the translations.\n"--locale fr" will write translations in the ./i18n/fr folder.',
   )
   .option(
     '--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',
+    '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. (default: false)',
   )
   .option(
     '--config <config>',
@@ -209,20 +170,10 @@ cli
   )
   .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',
+    'Allows to init new written messages with a given prefix. This might help you to highlight untranslated message by making them stand out in the UI (default: "")',
   )
-  .action(
-    async (
-      siteDir,
-      {locale = undefined, override = false, messagePrefix = '', config},
-    ) => {
-      writeTranslations(await resolveDir(siteDir), {
-        locale,
-        override,
-        config,
-        messagePrefix,
-      });
-    },
+  .action(async (siteDir, options) =>
+    writeTranslations(await resolveDir(siteDir), options),
   );
 
 cli

packages/docusaurus/src/commands/build.ts

@@ -31,7 +31,7 @@ import type {HelmetServerState} from 'react-helmet-async';
 
 export async function build(
   siteDir: string,
-  cliOptions: Partial<BuildCLIOptions> = {},
+  cliOptions: Partial<BuildCLIOptions>,
   // When running build, we force terminate the process to prevent async
   // operations from never returning. However, if run as part of docusaurus
   // deploy, we have to let deploy finish.

packages/docusaurus/src/commands/clear.ts

@@ -26,7 +26,7 @@ async function removePath(entry: {path: string; description: string}) {
   }
 }
 
-export async function clear(siteDir: string): Promise<unknown> {
+export async function clear(siteDir: string): Promise<void> {
   const generatedFolder = {
     path: path.join(siteDir, GENERATED_FILES_DIR_NAME),
     description: 'generated folder',
@@ -40,7 +40,7 @@ export async function clear(siteDir: string): Promise<unknown> {
     path: path.join(siteDir, p, '.cache'),
     description: 'Webpack persistent cache folder',
   }));
-  return Promise.all(
+  await Promise.all(
     [generatedFolder, buildFolder, ...cacheFolders].map(removePath),
   );
 }

packages/docusaurus/src/commands/deploy.ts

@@ -36,7 +36,7 @@ function shellExecLog(cmd: string) {
 
 export async function deploy(
   siteDir: string,
-  cliOptions: Partial<BuildCLIOptions> = {},
+  cliOptions: Partial<BuildCLIOptions>,
 ): Promise<void> {
   const {outDir, siteConfig, siteConfigPath} = await loadContext({
     siteDir,

packages/docusaurus/src/commands/serve.ts

@@ -12,13 +12,15 @@ import path from 'path';
 import {loadSiteConfig} from '../server/config';
 import {build} from './build';
 import {getCLIOptionHost, getCLIOptionPort} from './commandUtils';
+import {DEFAULT_BUILD_DIR_NAME} from '@docusaurus/utils';
 import type {ServeCLIOptions} from '@docusaurus/types';
 
 export async function serve(
   siteDir: string,
-  cliOptions: ServeCLIOptions,
+  cliOptions: Partial<ServeCLIOptions>,
 ): Promise<void> {
-  let dir = path.resolve(siteDir, cliOptions.dir);
+  const buildDir = cliOptions.dir ?? DEFAULT_BUILD_DIR_NAME;
+  let dir = path.resolve(siteDir, buildDir);
 
   if (cliOptions.build) {
     dir = await build(
@@ -69,7 +71,7 @@ export async function serve(
     });
   });
 
-  logger.success`Serving path=${cliOptions.dir} directory at url=${
+  logger.success`Serving path=${buildDir} directory at url=${
     servingUrl + baseUrl
   }.`;
   server.listen(port);

packages/docusaurus/src/commands/writeHeadingIds.ts

@@ -42,8 +42,8 @@ async function getPathsToWatch(siteDir: string): Promise<string[]> {
 
 export async function writeHeadingIds(
   siteDir: string,
-  files?: string[],
-  options?: WriteHeadingIDOptions,
+  files: string[],
+  options: WriteHeadingIDOptions,
 ): Promise<void> {
   const markdownFiles = await safeGlobby(
     files ?? (await getPathsToWatch(siteDir)),

packages/docusaurus/src/commands/writeTranslations.ts

@@ -74,7 +74,9 @@ async function writePluginTranslationFiles({
 
 export async function writeTranslations(
   siteDir: string,
-  options: WriteTranslationsOptions & ConfigOptions & {locale?: string},
+  options: Partial<
+    WriteTranslationsOptions & ConfigOptions & {locale?: string}
+  >,
 ): Promise<void> {
   const context = await loadContext({
     siteDir,