From 8d9e545f138f215277ba29093d358b463c47d935 Mon Sep 17 00:00:00 2001
From: Sam <sam@developersam.com>
Date: Thu, 25 Jun 2020 21:19:37 -0400
Subject: [PATCH] docs(v2): Document TypeScript support

---
 website/docs/lifecycle-apis.md     | 26 ++++++++++++++++
 website/docs/typescript-support.md | 50 ++++++++++++++++++++++++++++++
 website/sidebars.js                |  2 +-
 website/tsconfig.json              |  9 +++---
 4 files changed, 81 insertions(+), 6 deletions(-)
 create mode 100644 website/docs/typescript-support.md

diff --git a/website/docs/lifecycle-apis.md b/website/docs/lifecycle-apis.md
index 14f42c598ae8..68d43fd4f150 100644
--- a/website/docs/lifecycle-apis.md
+++ b/website/docs/lifecycle-apis.md
@@ -414,6 +414,32 @@ module.exports = function (context, options) {
 };
 ```
 
+## `getTypeScriptThemePath()`
+
+Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Instead, this path is purely for swizzling TypeScript theme components.
+
+If you want to support TypeScript component swizzling for your theme, you can make the path returned by `getTypeScriptThemePath()` be your source directory, and make path returned by `getThemePath()` be the compiled JavaScript output.
+
+Example:
+
+```js {6-13} title="my-theme/src/index.js"
+const path = require('path');
+
+module.exports = function (context, options) {
+  return {
+    name: 'name-of-my-theme',
+    getThemePath() {
+      // Where compiled JavaScript output lives
+      return path.join(__dirname, '..', 'lib', 'theme');
+    },
+    getTypeScriptThemePath() {
+      // Where TypeScript source code lives
+      return path.resolve(__dirname, './theme');
+    },
+  };
+};
+```
+
 ## `getClientModules()`
 
 Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.
diff --git a/website/docs/typescript-support.md b/website/docs/typescript-support.md
new file mode 100644
index 000000000000..7d5c488fab7c
--- /dev/null
+++ b/website/docs/typescript-support.md
@@ -0,0 +1,50 @@
+---
+id: typescript-support
+title: TypeScript Support
+---
+
+## Setup
+
+Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` to your project:
+
+```bash
+npm install --save-dev typescript @docusaurus/module-type-aliases
+```
+
+Then add `tsconfig.json` to your project root with following content:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "esModuleInterop": true,
+    "jsx": "react",
+    "lib": ["DOM"],
+    "noEmit": true,
+    "noImplicitAny": false
+  },
+  "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`.
+
+Now you can start writing TypeScript theme components.
+
+## Swizzling TypeScript theme components
+
+For themes that supports TypeScript theme components, you can add the `--typescript` flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`.
+
+```bash npm2yarn
+npm run swizzle @docusaurus/theme-classic Footer --typescript
+```
+
+At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./lifecycle-apis#gettypescriptthemepath).
diff --git a/website/sidebars.js b/website/sidebars.js
index 94f27479d461..7e37a0eb1400 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -16,7 +16,7 @@ module.exports = {
       type: 'category',
       label: 'Getting Started',
       collapsed: false,
-      items: ['installation', 'configuration'],
+      items: ['installation', 'configuration', 'typescript-support'],
     },
     {
       type: 'category',
diff --git a/website/tsconfig.json b/website/tsconfig.json
index 0f11fe0d4ae2..9b42be130582 100644
--- a/website/tsconfig.json
+++ b/website/tsconfig.json
@@ -1,13 +1,12 @@
 {
   // This file is not used in compilation. It is here just for a nice editor experience.
-  "extends": "../tsconfig.json",
   "compilerOptions": {
+    "allowJs": true,
+    "esModuleInterop": true,
+    "jsx": "react",
     "lib": ["DOM"],
-    "module": "esnext",
     "noEmit": true,
-    "noImplicitAny": false,
-    "jsx": "react",
-    "baseUrl": "src"
+    "noImplicitAny": false
   },
   "include": ["src/"]
 }