chore(v2): tighten up the TypeScript onboarding (#3244)

* Tighten up the TypeScript onboarding

* Extend the API to cover everything used in the classic theme

* Wrap up internal TS support

packages/docusaurus-module-type-aliases/package.json

@@ -6,5 +6,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "@types/react": "*",
+    "@types/react-helmet": "*",
+    "@types/react-router-dom": "*"
+  },
   "license": "MIT"
 }

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

@@ -53,6 +53,42 @@ declare module '@theme-original/*';
 
 declare module '@docusaurus/*';
 
+declare module '@docusaurus/Head' {
+  const helmet: typeof import('react-helmet').Helmet;
+  export default helmet;
+}
+
+declare module '@docusaurus/Link' {
+  type RRLinkProps = Partial<import('react-router-dom').LinkProps>;
+  type LinkProps = RRLinkProps & {
+    to?: string;
+    activeClassName?: string;
+    isNavLink?: boolean;
+  };
+  const Link: (props: LinkProps) => JSX.Element;
+  export default Link;
+}
+
+declare module '@docusaurus/router' {
+  export const Redirect: (props: {to: string}) => import('react').Component;
+  export function matchPath(
+    pathname: string,
+    opts: {path?: string; exact?: boolean; strict?: boolean},
+  ): boolean;
+  export function useLocation(): Location;
+}
+
+declare module '@docusaurus/useDocusaurusContext' {
+  export default function (): any;
+}
+
+declare module '@docusaurus/useBaseUrl' {
+  export default function (
+    relativePath: string | undefined,
+    opts?: {absolute?: true; forcePrependBaseUrl?: true},
+  ): string;
+}
+
 declare module '*.module.css' {
   const classes: {readonly [key: string]: string};
   export default classes;

packages/docusaurus/src/client/PendingNavigation.tsx

@@ -127,4 +127,4 @@ class PendingNavigation extends React.Component<Props, State> {
   }
 }
 
-export default withRouter(PendingNavigation);
+export default withRouter(PendingNavigation as any) as any;

packages/docusaurus/src/client/exports/Link.tsx

@@ -142,7 +142,7 @@ function Link({
       {...props}
       onMouseEnter={onMouseEnter}
       innerRef={handleRef}
-      to={targetLink}
+      to={targetLink || ''}
       // avoid "React does not recognize the `activeClassName` prop on a DOM element"
       {...(isNavLink && {activeClassName})}
     />

tsconfig.json

@@ -5,6 +5,7 @@
     "lib": ["es2017","es2019.array", "DOM"],
     "declaration": true,
     "declarationMap": true,
+    "jsx": "react",
 
     /* Strict Type-Checking Options */
     "strict": true,

website/docs/typescript-support.md

@@ -5,37 +5,22 @@ title: TypeScript Support
 
 ## Setup
 
-Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` to your project:
+Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` and some `@types` dependencies to your project:
 
 ```bash
-npm install --save-dev typescript @docusaurus/module-type-aliases
+npm install --save-dev typescript @docusaurus/module-type-aliases @types/react @types/react-router-dom @types/react-helmet @tsconfig/docusaurus
 ```
 
-Then add `tsconfig.json` to your project root with following content:
+Then add `tsconfig.json` to your project root with the following content:
 
 ```json title="tsconfig.json"
 {
-  "compilerOptions": {
-    "allowJs": true,
-    "esModuleInterop": true,
-    "jsx": "react",
-    "lib": ["DOM"],
-    "noEmit": true,
-    "noImplicitAny": false
-  },
+  "extends": "@tsconfig/docusaurus/tsconfig.json",
   "include": ["src/"]
 }
 ```
 
-Docusaurus doesn't use this `tsconfig.json` to compile your TypeScript. It is added just for a nicer Editor experience, although you can choose to run `tsc --noEmit` to type check your code for yourself.
-
-Then add `types.d.ts` in your `src` folder with the following content:
-
-```ts title="src/types.d.ts"
-/// <reference types="@docusaurus/module-type-aliases" />
-```
-
-This file makes TypeScript recognize various Docusaurus specific webpack aliases like `@theme`, `@docusaurus`, `@generated`.
+Docusaurus doesn't use this `tsconfig.json` to compile your project. It is added just for a nicer Editor experience, although you can choose to run `tsc` to type check your code for yourself or on CI.
 
 Now you can start writing TypeScript theme components.
 

yarn.lock

@@ -4120,6 +4120,13 @@
     "@types/webpack" "*"
     "@types/webpack-dev-server" "*"
 
+"@types/react-helmet@*":
+  version "6.1.0"
+  resolved "https://registry.yarnpkg.com/@types/react-helmet/-/react-helmet-6.1.0.tgz#af586ed685f4905e2adc7462d1d65ace52beee7a"
+  integrity sha512-PYRoU1XJFOzQ3BHvWL1T8iDNbRjdMDJMT5hFmZKGbsq09kbSqJy61uwEpTrbTNWDopVphUT34zUSVLK9pjsgYQ==
+  dependencies:
+    "@types/react" "*"
+
 "@types/react-helmet@^6.0.0":
   version "6.0.0"
   resolved "https://registry.yarnpkg.com/@types/react-helmet/-/react-helmet-6.0.0.tgz#5b74e44a12662ffb12d1c97ee702cf4e220958cf"
@@ -4144,6 +4151,15 @@
     "@types/react" "*"
     "@types/react-router" "*"
 
+"@types/react-router-dom@*":
+  version "5.1.5"
+  resolved "https://registry.yarnpkg.com/@types/react-router-dom/-/react-router-dom-5.1.5.tgz#7c334a2ea785dbad2b2dcdd83d2cf3d9973da090"
+  integrity sha512-ArBM4B1g3BWLGbaGvwBGO75GNFbLDUthrDojV2vHLih/Tq8M+tgvY1DSwkuNrPSwdp/GUL93WSEpTZs8nVyJLw==
+  dependencies:
+    "@types/history" "*"
+    "@types/react" "*"
+    "@types/react-router" "*"
+
 "@types/react-router@*":
   version "5.1.7"
   resolved "https://registry.yarnpkg.com/@types/react-router/-/react-router-5.1.7.tgz#e9d12ed7dcfc79187e4d36667745b69a5aa11556"