feat(v2): new docusaurus clear command (#3446)

* feat: new docusaurus clear command

* Update packages/docusaurus/bin/docusaurus.js

Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>

* docs: new docusaurus clear command

* fix doc

* update monorepo clear cmd

* make clear async function wait for deletes to complete + factorize a bit

* prettier fix

* better clear docs

Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>
Co-authored-by: slorber <lorber.sebastien@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

package.json

@@ -40,7 +40,7 @@
     "test": "jest",
     "test:build:v2": "./admin/scripts/test-release.sh",
     "watch": "yarn lerna run --parallel --no-private watch",
-    "clear": "yarn rimraf website/.docusaurus && rimraf -rf website/node_modules/.cache && yarn lerna exec 'yarn rimraf lib' --ignore docusaurus",
+    "clear": "yarn workspace docusaurus-2-website clear && yarn lerna exec 'yarn rimraf lib' --ignore docusaurus",
     "test:v1Migration:migrate": "rimraf website-1.x-migrated && docusaurus-migrate migrate ./website-1.x ./website-1.x-migrated && sed -i -- 's/docusaurus-1-website/docusaurus-1-website-migrated/g;' website-1.x-migrated/package.json",
     "test:v1Migration:start": "yarn workspace docusaurus-1-website-migrated start",
     "test:v1Migration:build": "yarn workspace docusaurus-1-website-migrated build",

packages/docusaurus/bin/docusaurus.js

@@ -18,6 +18,7 @@ const {
   start,
   externalCommand,
   serve,
+  clear,
 } = require('../lib');
 const requiredVersion = require('../package.json').engines.node;
 const pkg = require('../package.json');
@@ -187,6 +188,13 @@ cli
     },
   );
 
+cli
+  .command('clear')
+  .description('Remove build artifacts')
+  .action(() => {
+    wrapCommand(clear)(path.resolve('.'));
+  });
+
 cli.arguments('<command>').action((cmd) => {
   cli.outputHelp();
   console.log(`  ${chalk.red(`\n  Unknown command ${chalk.yellow(cmd)}.`)}`);
@@ -194,7 +202,9 @@ cli.arguments('<command>').action((cmd) => {
 });
 
 function isInternalCommand(command) {
-  return ['start', 'build', 'swizzle', 'deploy', 'serve'].includes(command);
+  return ['start', 'build', 'swizzle', 'deploy', 'serve', 'clear'].includes(
+    command,
+  );
 }
 
 if (!isInternalCommand(process.argv.slice(2)[0])) {

packages/docusaurus/src/commands/clear.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 fs from 'fs-extra';
+import path from 'path';
+import chalk = require('chalk');
+import {BUILD_DIR_NAME, GENERATED_FILES_DIR_NAME} from '../constants';
+
+function removePath(fsPath: string) {
+  return fs
+    .remove(path.join(fsPath))
+    .then(() => {
+      console.log(`${chalk.green(`Removing ${fsPath}`)}`);
+    })
+    .catch((err) => {
+      console.error(`Could not remove ${fsPath}`);
+      console.error(err);
+    });
+}
+
+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, 'node_modules/.cache/cache-loader')),
+  ]);
+}

packages/docusaurus/src/index.ts

@@ -11,3 +11,4 @@ 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';

website/docs/cli.md

@@ -14,7 +14,8 @@ Once your website is bootstrapped, the website source will contain the Docusauru
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
-    "deploy": "docusaurus deploy"
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear"
   }
 }
 ```
@@ -126,3 +127,9 @@ Serve your built website locally.
 | `--dir` | `build` | The full path for the output directory, relative to the current workspace |
 | `--build` | `false` | Build website before serving |
 | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
+
+### `docusaurus clear`
+
+Clear a Docusaurus site's generated assets, caches, build artifacts...
+
+We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.

website/package.json

@@ -8,6 +8,7 @@
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
     "start:baseUrl": "BASE_URL='/build/' yarn start",
     "build:baseUrl": "BASE_URL='/build/' yarn build",
     "start:bootstrap": "DOCUSAURUS_PRESET=bootstrap yarn start",