feat(core): rework swizzle CLI (#6243)

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

.eslintignore

@@ -17,3 +17,5 @@ copyUntypedFiles.mjs
 
 packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/facebook/.eslintrc.js
+
+website/_dogfooding/_swizzle_theme_tests

.eslintrc.js

@@ -260,7 +260,11 @@ module.exports = {
     'no-unused-vars': OFF,
     '@typescript-eslint/no-unused-vars': [
       ERROR,
-      {argsIgnorePattern: '^_', ignoreRestSiblings: true},
+      {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        ignoreRestSiblings: true,
+      },
     ],
   },
   overrides: [

.github/workflows/tests-swizzle.yml

@@ -0,0 +1,37 @@
+name: Swizzle Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - packages/**
+
+jobs:
+  test:
+    name: Swizzle
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        action: ['eject', 'wrap']
+        variant: ['js', 'ts']
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: 14
+          cache: yarn
+      - name: Installation
+        run: yarn
+
+      # Swizzle all the theme components
+      - name: Swizzle (${{matrix.action}} - ${{matrix.variant}})
+        run: yarn workspace website test:swizzle:${{matrix.action}}:${{matrix.variant}}
+      # Build swizzled site
+      - name: Build website
+        run: yarn build:website:fast
+      # Ensure swizzled site still typechecks
+      - name: TypeCheck website
+        run: yarn workspace website typecheck

.github/workflows/tests-windows.yml

@@ -34,5 +34,10 @@ jobs:
           mkdir -p "website/_dogfooding/_pages tests/deep-file-path-test/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar/foo/bar"
           cd "$_"
           echo "# hello" > test-file.md
+      # Lightweight version of tests-swizzle.yml workflow, but for Windows
+      - name: Swizzle Wrap TS
+        run: yarn workspace website test:swizzle:wrap:ts
       - name: Docusaurus Build
-        run: yarn build:website --locale en
+        run: yarn build:website:fast
+      - name: TypeCheck website
+        run: yarn workspace website typecheck

.gitignore

@@ -31,6 +31,8 @@ website/changelog
 !website/netlifyDeployPreview/index.html
 !website/netlifyDeployPreview/_redirects
 
+website/_dogfooding/_swizzle_theme_tests
+
 website/i18n/**/*
 #!website/i18n/fr
 #!website/i18n/fr/**/*

.prettierignore

@@ -20,3 +20,6 @@ website/versioned_sidebars/*.json
 
 examples/
 website/static/katex/katex.min.css
+
+website/changelog/_swizzle_theme_tests
+website/_dogfooding/_swizzle_theme_tests

.stylelintignore

@@ -2,6 +2,7 @@
 *
 !*/
 !*.css
+__tests__/
 build
 coverage
 examples/

jest.config.mjs

@@ -10,6 +10,7 @@ import {fileURLToPath} from 'url';
 const ignorePatterns = [
   '/node_modules/',
   '__fixtures__',
+  '/testUtils.ts',
   '/packages/docusaurus/lib',
   '/packages/docusaurus-utils/lib',
   '/packages/docusaurus-utils-validation/lib',

package.json

@@ -23,7 +23,9 @@
     "build:website": "yarn workspace website build",
     "build:website:baseUrl": "yarn workspace website build:baseUrl",
     "build:website:blogOnly": "yarn workspace website build:blogOnly",
-    "build:website:deployPreview": "cross-env NETLIFY=true CONTEXT='deploy-preview' yarn workspace website build",
+    "build:website:deployPreview:testWrap": "yarn workspace website test:swizzle:wrap:ts",
+    "build:website:deployPreview:build": "cross-env NETLIFY=true CONTEXT='deploy-preview' yarn workspace website build",
+    "build:website:deployPreview": "yarn build:website:deployPreview:testWrap && yarn build:website:deployPreview:build",
     "build:website:fast": "yarn workspace website build:fast",
     "build:website:en": "yarn workspace website build --locale en",
     "clear:website": "yarn workspace website clear",

packages/docusaurus-logger/src/index.ts

@@ -120,6 +120,10 @@ function success(msg: unknown, ...values: InterpolatableValue[]): void {
   );
 }
 
+function newLine(): void {
+  console.log();
+}
+
 const logger = {
   red: chalk.red,
   yellow: chalk.yellow,
@@ -136,6 +140,7 @@ const logger = {
   warn,
   error,
   success,
+  newLine,
 };
 
 // TODO remove when migrating to ESM

packages/docusaurus-module-type-aliases/src/index.d.ts

@@ -83,6 +83,7 @@ declare module '@generated/codeTranslations' {
 }
 
 declare module '@theme-original/*';
+declare module '@theme-init/*';
 
 declare module '@theme/Error' {
   export interface Props {

packages/docusaurus-plugin-debug/src/index.ts

@@ -26,7 +26,6 @@ export default function pluginDebug({
     getThemePath() {
       return path.resolve(__dirname, '../lib/theme');
     },
-
     getTypeScriptThemePath() {
       return path.resolve(__dirname, '../src/theme');
     },

packages/docusaurus-plugin-pwa/src/index.ts

@@ -64,7 +64,10 @@ export default function pluginPWA(
     name: 'docusaurus-plugin-pwa',
 
     getThemePath() {
-      return path.resolve(__dirname, './theme');
+      return path.resolve(__dirname, '../lib/theme');
+    },
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, '../src/theme');
     },
 
     getClientModules() {

packages/docusaurus-theme-classic/src/getSwizzleConfig.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 type {SwizzleConfig} from '@docusaurus/types';
+
+export default function getSwizzleConfig(): SwizzleConfig {
+  return {
+    components: {
+      CodeBlock: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description:
+          'The component used to render multi-line code blocks, generally used in Markdown files.',
+      },
+      DocSidebar: {
+        actions: {
+          wrap: 'safe',
+          eject: 'unsafe', // too much technical code in sidebar, not very safe atm
+        },
+        description: 'The sidebar component on docs pages',
+      },
+      Footer: {
+        actions: {
+          wrap: 'safe',
+          eject: 'unsafe', // TODO split footer into smaller parts
+        },
+        description: "The footer component of you site's layout",
+      },
+      NotFound: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description:
+          'The global 404 page of your site, meant to be ejected and customized',
+      },
+      SearchBar: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        // TODO how to describe this one properly?
+        // By default it's an empty placeholder for the user to fill
+        description:
+          'The search bar component of your site, appearing in the navbar.',
+      },
+      IconArrow: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The arrow icon component',
+      },
+      IconEdit: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The edit icon component',
+      },
+      IconMenu: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The menu icon component',
+      },
+
+      'prism-include-languages': {
+        actions: {
+          wrap: 'forbidden', // not a component!
+          eject: 'safe',
+        },
+        description:
+          'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',
+      },
+      MDXComponents: {
+        actions: {
+          wrap: 'forbidden', /// TODO allow wrapping objects???
+          eject: 'safe',
+        },
+        description:
+          'The MDX components to use for rendering MDX files. Meant to be ejected.',
+      },
+
+      // TODO should probably not even appear here
+      'NavbarItem/utils': {
+        actions: {
+          wrap: 'forbidden',
+          eject: 'forbidden',
+        },
+      },
+    },
+  };
+}

packages/docusaurus-theme-classic/src/index.ts

@@ -207,21 +207,5 @@ ${announcementBar ? AnnouncementBarInlineJavaScript : ''}
   };
 }
 
-const swizzleAllowedComponents = [
-  'CodeBlock',
-  'DocSidebar',
-  'Footer',
-  'NotFound',
-  'SearchBar',
-  'IconArrow',
-  'IconEdit',
-  'IconMenu',
-  'hooks/useTheme',
-  'prism-include-languages',
-];
-
-export function getSwizzleComponentList(): string[] {
-  return swizzleAllowedComponents;
-}
-
+export {default as getSwizzleConfig} from './getSwizzleConfig';
 export {validateThemeConfig} from './validateThemeConfig';

packages/docusaurus-theme-search-algolia/src/index.ts

@@ -47,11 +47,10 @@ export default function themeSearchAlgolia(context: LoadContext): Plugin<void> {
     name: 'docusaurus-theme-search-algolia',
 
     getThemePath() {
-      return path.resolve(__dirname, './theme');
+      return path.resolve(__dirname, '../lib/theme');
     },
-
     getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
+      return path.resolve(__dirname, '../src/theme');
     },
 
     getDefaultCodeTranslationMessages() {

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

@@ -316,13 +316,30 @@ export type LoadedPlugin<Content = unknown> = InitializedPlugin<Content> & {
   readonly content: Content;
 };
 
+export type SwizzleAction = 'eject' | 'wrap';
+export type SwizzleActionStatus = 'safe' | 'unsafe' | 'forbidden';
+
+export type SwizzleComponentConfig = {
+  actions: Record<SwizzleAction, SwizzleActionStatus>;
+  description?: string;
+};
+
+export type SwizzleConfig = {
+  components: Record<string, SwizzleComponentConfig>;
+  // Other settings could be added here,
+  // For example: the ability to declare the config as exhaustive
+  // so that we can emit errors
+};
+
 export type PluginModule = {
   <Options, Content>(context: LoadContext, options: Options):
     | Plugin<Content>
     | Promise<Plugin<Content>>;
   validateOptions?: <T>(data: OptionValidationContext<T>) => T;
   validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
-  getSwizzleComponentList?: () => string[];
+
+  getSwizzleComponentList?: () => string[] | undefined; // TODO deprecate this one later
+  getSwizzleConfig?: () => SwizzleConfig | undefined;
 };
 
 export type ImportedPluginModule = PluginModule & {

packages/docusaurus/bin/docusaurus.mjs

@@ -68,20 +68,28 @@ cli
 
 cli
   .command('swizzle [themeName] [componentName] [siteDir]')
-  .description('Copy the theme files into website folder for customization.')
+  .description(
+    'Wraps or ejects the original theme files into website folder for customization.',
+  )
+  .option(
+    '-w, --wrap',
+    'Creates a wrapper around the original theme component.\nAllows rendering other components before/after the original theme component.',
+  )
+  .option(
+    '-e, --eject',
+    'Ejects the full source code of the original theme component.\nAllows overriding the original component entirely with your own UI and logic.',
+  )
+  .option(
+    '-l, --list',
+    'only list the available themes/components without further prompting (default: false)',
+  )
   .option(
-    '--typescript',
+    '-t, --typescript',
     'copy TypeScript theme files when possible (default: false)',
   )
-  .option('--danger', 'enable swizzle for internal component of themes')
-  .action(async (themeName, componentName, siteDir, {typescript, danger}) => {
-    swizzle(
-      await resolveDir(siteDir),
-      themeName,
-      componentName,
-      typescript,
-      danger,
-    );
+  .option('--danger', 'enable swizzle for unsafe component of themes')
+  .action(async (themeName, componentName, siteDir, options) => {
+    swizzle(await resolveDir(siteDir), themeName, componentName, options);
   });
 
 cli

packages/docusaurus/package.json

@@ -56,6 +56,7 @@
     "boxen": "^6.2.1",
     "chokidar": "^3.5.3",
     "clean-css": "^5.2.4",
+    "cli-table3": "^0.6.1",
     "combine-promises": "^1.1.0",
     "commander": "^5.1.0",
     "copy-webpack-plugin": "^10.2.4",
@@ -117,7 +118,8 @@
     "@types/wait-on": "^5.3.1",
     "@types/webpack-bundle-analyzer": "^4.4.1",
     "react-test-renderer": "^17.0.2",
-    "tmp-promise": "^3.0.3"
+    "tmp-promise": "^3.0.3",
+    "tree-node-cli": "^1.5.2"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",