feat(v2): Support swizzling TypeScript components (#2671)

* feat(v2): Support swizzling TypeScript components * Add tsc --noEmit to tsc script in theme-classic Now everything can pass the type checker! (although still a lot of any) * Add tsconfig and types.d.ts to website Improve developer experience. As an example, I converted NotFound to tsx * Apply type annotation suggestions * Do not fallback to `getThemePath` if getTypeScriptThemePath is undefined * Fix tsc * Add module declaration for @theme-original/* * Move babel cli to root package.json
facebook · Jun 25, 2020 · 5ccd24c · 5ccd24c
1 parent 20930dc
commit 5ccd24c
Show file tree

Hide file tree

Showing 59 changed files with 345 additions and 108 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -22,6 +22,7 @@ packages/docusaurus-plugin-debug/lib/
 packages/docusaurus-plugin-sitemap/lib/
 packages/docusaurus-plugin-ideal-image/lib/
 packages/docusaurus-plugin-ideal-image/copyUntypedFiles.js
+packages/docusaurus-theme-classic/lib/
 
 packages/docusaurus-1.x/.eslintrc.js
 packages/docusaurus-init/templates/facebook/.eslintrc.js
diff --git a/.gitignore b/.gitignore
@@ -26,3 +26,4 @@ packages/docusaurus-plugin-content-pages/lib/
 packages/docusaurus-plugin-debug/lib/
 packages/docusaurus-plugin-sitemap/lib/
 packages/docusaurus-plugin-ideal-image/lib/
+packages/docusaurus-theme-classic/lib/
diff --git a/package.json b/package.json
@@ -34,6 +34,7 @@
   },
   "devDependencies": {
     "@babel/core": "^7.9.0",
+    "@babel/cli": "^7.9.0",
     "@babel/plugin-proposal-nullish-coalescing-operator": "^7.8.3",
     "@babel/plugin-proposal-optional-chaining": "^7.9.0",
     "@babel/preset-typescript": "^7.9.0",
@@ -52,6 +53,7 @@
     "@types/lodash.pick": "^4.4.6",
     "@types/lodash.pickby": "^4.6.6",
     "@types/node": "^13.11.0",
+    "@types/prismjs": "^1.16.1",
     "@types/react": "^16.9.38",
     "@types/react-dev-utils": "^9.0.1",
     "@types/react-helmet": "^6.0.0",

diff --git a/packages/docusaurus-module-type-aliases/src/index.d.ts b/packages/docusaurus-module-type-aliases/src/index.d.ts
@@ -37,10 +37,9 @@ declare module '@generated/routesChunkNames' {
   export default routesChunkNames;
 }
 
-declare module '@theme/*' {
-  const component: any;
-  export default component;
-}
+declare module '@theme/*';
+
+declare module '@theme-original/*';
 
 declare module '@docusaurus/*';
 

diff --git a/packages/docusaurus-theme-classic/babel.config.js b/packages/docusaurus-theme-classic/babel.config.js
@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+module.exports = {
+  presets: [['@babel/preset-typescript', {isTSX: true, allExtensions: true}]],
+};
diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json
@@ -7,6 +7,11 @@
     "access": "public"
   },
   "license": "MIT",
+  "scripts": {
+    "tsc": "tsc --noEmit && yarn babel && yarn prettier",
+    "babel": "babel src -d lib --extensions \".tsx,.ts\" --copy-files",
+    "prettier": "prettier --config ../../.prettierrc --write \"**/*.{js,ts}\""
+  },
   "dependencies": {
     "@hapi/joi": "^17.1.1",
     "@mdx-js/mdx": "^1.5.8",
@@ -21,6 +26,9 @@
     "react-router-dom": "^5.1.2",
     "react-toggle": "^4.1.1"
   },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^2.0.0-alpha.58"
+  },
   "peerDependencies": {
     "@docusaurus/core": "^2.0.0",
     "react": "^16.8.4",

diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js
@@ -61,6 +61,10 @@ module.exports = function (context, options) {
     name: 'docusaurus-theme-classic',
 
     getThemePath() {
+      return path.join(__dirname, '..', 'lib', 'theme');
+    },
+
+    getTypeScriptThemePath() {
       return path.resolve(__dirname, './theme');
     },
 

diff --git a/...lassic/src/theme/AnnouncementBar/index.js → ...assic/src/theme/AnnouncementBar/index.tsx b/...lassic/src/theme/AnnouncementBar/index.js → ...assic/src/theme/AnnouncementBar/index.tsx
@@ -11,9 +11,9 @@ import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
 
 import styles from './styles.module.css';
 
-function AnnouncementBar() {
+function AnnouncementBar(): JSX.Element | null {
   const {
-    siteConfig: {themeConfig: {announcementBar = {}}} = {},
+    siteConfig: {themeConfig: {announcementBar = {}} = {}} = {},
   } = useDocusaurusContext();
   const {content, backgroundColor, textColor} = announcementBar;
   const {

diff --git a/...e-classic/src/theme/BlogListPage/index.js → ...-classic/src/theme/BlogListPage/index.tsx b/...e-classic/src/theme/BlogListPage/index.js → ...-classic/src/theme/BlogListPage/index.tsx
@@ -12,7 +12,12 @@ import Layout from '@theme/Layout';
 import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';
 
-function BlogListPage(props) {
+type Props = {
+  metadata: {permalink: string; title: string};
+  items: {content}[];
+};
+
+function BlogListPage(props: Props): JSX.Element {
   const {metadata, items} = props;
   const {
     siteConfig: {title: siteTitle},

diff --git a/...ssic/src/theme/BlogListPaginator/index.js → ...sic/src/theme/BlogListPaginator/index.tsx b/...ssic/src/theme/BlogListPaginator/index.js → ...sic/src/theme/BlogListPaginator/index.tsx
@@ -8,7 +8,7 @@
 import React from 'react';
 import Link from '@docusaurus/Link';
 
-function BlogListPaginator(props) {
+function BlogListPaginator(props): JSX.Element {
   const {metadata} = props;
   const {previousPage, nextPage} = metadata;
 

diff --git a/...e-classic/src/theme/BlogPostItem/index.js → ...-classic/src/theme/BlogPostItem/index.tsx b/...e-classic/src/theme/BlogPostItem/index.js → ...-classic/src/theme/BlogPostItem/index.tsx
@@ -31,7 +31,7 @@ const MONTHS = [
   'December',
 ];
 
-function BlogPostItem(props) {
+function BlogPostItem(props): JSX.Element {
   const {
     children,
     frontMatter,

diff --git a/...e-classic/src/theme/BlogPostPage/index.js → ...-classic/src/theme/BlogPostPage/index.tsx b/...e-classic/src/theme/BlogPostPage/index.js → ...-classic/src/theme/BlogPostPage/index.tsx
@@ -11,7 +11,7 @@ import Layout from '@theme/Layout';
 import BlogPostItem from '@theme/BlogPostItem';
 import BlogPostPaginator from '@theme/BlogPostPaginator';
 
-function BlogPostPage(props) {
+function BlogPostPage(props): JSX.Element {
   const {content: BlogPostContents} = props;
   const {frontMatter, metadata} = BlogPostContents;
   const {title, description, nextItem, prevItem, editUrl} = metadata;

diff --git a/...ssic/src/theme/BlogPostPaginator/index.js → ...sic/src/theme/BlogPostPaginator/index.tsx b/...ssic/src/theme/BlogPostPaginator/index.js → ...sic/src/theme/BlogPostPaginator/index.tsx
@@ -8,7 +8,7 @@
 import React from 'react';
 import Link from '@docusaurus/Link';
 
-function BlogPostPaginator(props) {
+function BlogPostPaginator(props): JSX.Element {
   const {nextItem, prevItem} = props;
 
   return (

diff --git a/...assic/src/theme/BlogTagsListPage/index.js → ...ssic/src/theme/BlogTagsListPage/index.tsx b/...assic/src/theme/BlogTagsListPage/index.js → ...ssic/src/theme/BlogTagsListPage/index.tsx
@@ -10,15 +10,17 @@ import React from 'react';
 import Layout from '@theme/Layout';
 import Link from '@docusaurus/Link';
 
-function getCategoryOfTag(tag) {
+function getCategoryOfTag(tag: string) {
   // tag's category should be customizable
   return tag[0].toUpperCase();
 }
 
-function BlogTagsListPage(props) {
+type Tag = {permalink: string; name: string; count: number};
+
+function BlogTagsListPage(props: {tags: Record<string, Tag>}): JSX.Element {
   const {tags} = props;
 
-  const tagCategories = {};
+  const tagCategories: {[category: string]: string[]} = {};
   Object.keys(tags).forEach((tag) => {
     const category = getCategoryOfTag(tag);
     tagCategories[category] = tagCategories[category] || [];

diff --git a/...ssic/src/theme/BlogTagsPostsPage/index.js → ...sic/src/theme/BlogTagsPostsPage/index.tsx b/...ssic/src/theme/BlogTagsPostsPage/index.js → ...sic/src/theme/BlogTagsPostsPage/index.tsx
@@ -11,11 +11,11 @@ import Layout from '@theme/Layout';
 import BlogPostItem from '@theme/BlogPostItem';
 import Link from '@docusaurus/Link';
 
-function pluralize(count, word) {
+function pluralize(count: number, word: string) {
   return count > 1 ? `${word}s` : word;
 }
 
-function BlogTagsPostPage(props) {
+function BlogTagsPostPage(props): JSX.Element {
   const {metadata, items} = props;
   const {allTagsPath, name: tagName, count} = metadata;
 

diff --git a/...heme-classic/src/theme/CodeBlock/index.js → ...eme-classic/src/theme/CodeBlock/index.tsx b/...heme-classic/src/theme/CodeBlock/index.js → ...eme-classic/src/theme/CodeBlock/index.tsx
@@ -87,7 +87,15 @@ const highlightDirectiveRegex = (lang) => {
 };
 const codeBlockTitleRegex = /title=".*"/;
 
-export default ({children, className: languageClassName, metastring}) => {
+export default ({
+  children,
+  className: languageClassName,
+  metastring,
+}: {
+  children: string;
+  className: string;
+  metastring: string;
+}): JSX.Element => {
   const {
     siteConfig: {
       themeConfig: {prism = {}},
@@ -108,21 +116,25 @@ export default ({children, className: languageClassName, metastring}) => {
   }, []);
 
   const button = useRef(null);
-  let highlightLines = [];
+  let highlightLines: number[] = [];
   let codeBlockTitle = '';
 
   const prismTheme = usePrismTheme();
 
   if (metastring && highlightLinesRangeRegex.test(metastring)) {
-    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)[1];
+    // Tested above
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)![1];
     highlightLines = rangeParser
       .parse(highlightLinesRange)
       .filter((n) => n > 0);
   }
 
   if (metastring && codeBlockTitleRegex.test(metastring)) {
+    // Tested above
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     codeBlockTitle = metastring
-      .match(codeBlockTitleRegex)[0]
+      .match(codeBlockTitleRegex)![0]
       .split('title=')[1]
       .replace(/"+/g, '');
   }
@@ -151,7 +163,10 @@ export default ({children, className: languageClassName, metastring}) => {
       if (match !== null) {
         const directive = match
           .slice(1)
-          .reduce((final, item) => final || item, undefined);
+          .reduce(
+            (final: string | undefined, item) => final || item,
+            undefined,
+          );
         switch (directive) {
           case 'highlight-next-line':
             range += `${lineNumber},`;
@@ -188,9 +203,10 @@ export default ({children, className: languageClassName, metastring}) => {
   return (
     <Highlight
       {...defaultProps}
-      key={mounted}
+      key={String(mounted)}
       theme={prismTheme}
       code={code}
+      // @ts-expect-error: prism-react-renderer doesn't export Language type
       language={language}>
       {({className, style, tokens, getLineProps, getTokenProps}) => (
         <>
@@ -211,7 +227,7 @@ export default ({children, className: languageClassName, metastring}) => {
               {showCopied ? 'Copied' : 'Copy'}
             </button>
             <div
-              tabIndex="0"
+              tabIndex={0}
               className={clsx(className, styles.codeBlock, {
                 [styles.codeBlockWithTitle]: codeBlockTitle,
               })}>

diff --git a/...-theme-classic/src/theme/DocItem/index.js → ...theme-classic/src/theme/DocItem/index.tsx b/...-theme-classic/src/theme/DocItem/index.js → ...theme-classic/src/theme/DocItem/index.tsx
@@ -33,7 +33,7 @@ function DocTOC({headings}) {
 }
 
 /* eslint-disable jsx-a11y/control-has-associated-label */
-function Headings({headings, isChild}) {
+function Headings({headings, isChild}: {headings; isChild?: boolean}) {
   if (!headings.length) {
     return null;
   }
@@ -58,7 +58,7 @@ function Headings({headings, isChild}) {
   );
 }
 
-function DocItem(props) {
+function DocItem(props): JSX.Element {
   const {siteConfig = {}} = useDocusaurusContext();
   const {url: siteUrl, title: siteTitle} = siteConfig;
   const {content: DocContent} = props;

diff --git a/...-theme-classic/src/theme/DocPage/index.js → ...theme-classic/src/theme/DocPage/index.tsx b/...-theme-classic/src/theme/DocPage/index.js → ...theme-classic/src/theme/DocPage/index.tsx
@@ -18,7 +18,7 @@ import {matchPath} from '@docusaurus/router';
 
 import styles from './styles.module.css';
 
-function DocPage(props) {
+function DocPage(props): JSX.Element {
   const {route: baseRoute, docsMetadata, location} = props;
   // case-sensitive route such as it is defined in the sidebar
   const currentRoute =

diff --git a/...e-classic/src/theme/DocPaginator/index.js → ...-classic/src/theme/DocPaginator/index.tsx b/...e-classic/src/theme/DocPaginator/index.js → ...-classic/src/theme/DocPaginator/index.tsx
@@ -8,7 +8,13 @@
 import React from 'react';
 import Link from '@docusaurus/Link';
 
-function DocPaginator(props) {
+type PageInfo = {permalink: string; title: string};
+
+type Props = {
+  metadata: {previous: PageInfo; next: PageInfo};
+};
+
+function DocPaginator(props: Props): JSX.Element {
   const {metadata} = props;
 
   return (

diff --git a/...eme-classic/src/theme/DocSidebar/index.js → ...me-classic/src/theme/DocSidebar/index.tsx b/...eme-classic/src/theme/DocSidebar/index.js → ...me-classic/src/theme/DocSidebar/index.tsx
@@ -163,11 +163,11 @@ function DocSidebarItem(props) {
   }
 }
 
-function DocSidebar(props) {
+function DocSidebar(props): JSX.Element | null {
   const [showResponsiveSidebar, setShowResponsiveSidebar] = useState(false);
   const {
     siteConfig: {
-      themeConfig: {navbar: {title, hideOnScroll = false} = {}},
+      themeConfig: {navbar: {title = '', hideOnScroll = false} = {}} = {},
     } = {},
     isClient,
   } = useDocusaurusContext();

diff --git a/...s-theme-classic/src/theme/Footer/index.js → ...-theme-classic/src/theme/Footer/index.tsx b/...s-theme-classic/src/theme/Footer/index.js → ...-theme-classic/src/theme/Footer/index.tsx
@@ -39,7 +39,7 @@ const FooterLogo = ({url, alt}) => (
   <img className="footer__logo" alt={alt} src={url} />
 );
 
-function Footer() {
+function Footer(): JSX.Element | null {
   const context = useDocusaurusContext();
   const {siteConfig = {}} = context;
   const {themeConfig = {}} = siteConfig;

diff --git a/...-theme-classic/src/theme/Heading/index.js → ...theme-classic/src/theme/Heading/index.tsx b/...-theme-classic/src/theme/Heading/index.js → ...theme-classic/src/theme/Heading/index.tsx
@@ -7,14 +7,14 @@
 
 /* eslint-disable jsx-a11y/anchor-has-content, jsx-a11y/anchor-is-valid */
 
-import React from 'react';
+import React, {ComponentType} from 'react';
 import clsx from 'clsx';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 import './styles.css';
 import styles from './styles.module.css';
 
-const Heading = (Tag) =>
+const Heading = (Tag: ComponentType): ((props) => JSX.Element) =>
   function TargetComponent({id, ...props}) {
     const {
       siteConfig: {
@@ -30,7 +30,7 @@ const Heading = (Tag) =>
       <Tag {...props}>
         <a
           aria-hidden="true"
-          tabIndex="-1"
+          tabIndex={-1}
           className={clsx('anchor', {
             [styles.enhancedAnchor]: !hideOnScroll,
           })}
@@ -39,7 +39,7 @@ const Heading = (Tag) =>
         {props.children}
         <a
           aria-hidden="true"
-          tabIndex="-1"
+          tabIndex={-1}
           className="hash-link"
           href={`#${id}`}
           title="Direct link to heading">

diff --git a/...s-theme-classic/src/theme/Layout/index.js → ...-theme-classic/src/theme/Layout/index.tsx b/...s-theme-classic/src/theme/Layout/index.js → ...-theme-classic/src/theme/Layout/index.tsx
@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {ReactNode} from 'react';
 import Head from '@docusaurus/Head';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
@@ -18,7 +18,18 @@ import Footer from '@theme/Footer';
 
 import './styles.css';
 
-function Layout(props) {
+type Props = {
+  children: ReactNode;
+  title?: string;
+  noFooter?: boolean;
+  description?: string;
+  image?: string;
+  keywords?: string[];
+  permalink?: string;
+  version?: string;
+};
+
+function Layout(props: Props): JSX.Element {
   const {siteConfig = {}} = useDocusaurusContext();
   const {
     favicon,