refactor(v2): Convert docusaurus-core to TypeScript

[SamChou19815]

Motivation

I believe this is the first step to support #2470. In order to use write TypeScript theme components, we should first have solid types for the core. Instead of writing d.ts files manually, it's better to write the core in TS and let TS generate correct type declaration files.

Have you read the Contributing Guidelines on pull requests?

Yes

Implementation

It turns out that rewriting the code in TS is not as simple as changing the file extension and add a bunch of missing type annotations. It's complicated for the following reasons:

1. Docusaurus has setup webpack aliases like @docusaurus, @generated, @theme. TypeScript doesn't understand these aliases natively.
2. Part of the docusaurus core runs in browser (ESModule) and part of them runs on node (CommonJS). We somehow need to typescript to emit code for two different module formats.
3. One file client/serverEntry.js imports a package.json file outside of TypeScript 'rootDir' and TS is not happy about that.

My solutions:

1. Add a types.d.ts that declares those modules. For @docusaurus/..., I replaced that with relative imports. For @generated/..., I looked at the generated files in website/.docusaurus and add the types. I left some types as any since they appeared to be too dynamic. For @theme, I added a blanket rule declare module '@theme/*' { const component: any; export default component }, since I believe it's better to deal with this problem once we start to converting themes to TS.
2. Create two tsconfig, once for src/client only and one for everything else but excluding client. The tsconfig for src/client emits ESModule code and the other one emits commonjs code.
3. Do not migrate client/serverEntry.js to TS. I tried to replace that import with a file read, but it breaks the build.

Test Plan

Check each page in the preview website. Nothing breaks.

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit bf4c7f7

https://deploy-preview-2578--docusaurus-2.netlify.com

[yangshun]

I'm not familiar with our TypeScript setup, but if it builds and CI passes, it should be good! Thanks Sam!

[kripod]

Fantastic work!

As for theme resolution, I'm currently using the following approach in my website's tsconfig.json:

{
  "include": ["./src/"],
  "compilerOptions": {
    "noEmit": true,
    "baseUrl": "./",
    "paths": {
      "@site/*": [
        // https://v2.docusaurus.io/docs/versioning/#use-absolute-import-within-the-docs
        "./*"
      ],
      "@theme/*": [
        // https://v2.docusaurus.io/docs/using-themes/#theme-components
        "./src/theme/*",
        "./node_modules/@docusaurus/theme-classic/src/theme/*",
        "./node_modules/@docusaurus/core/lib/client/theme-fallback/*"
      ],
      "@docusaurus/*": [
        "./node_modules/@docusaurus/core/lib/client/exports/*"
      ]
    }
  }
}

The @docusaurus/* alias may be dropped by this PR. However, I think the docs should have instructions about adding aliases for @site/* and @theme/*, as shown above.