refactor(v2): Expose docusaurus module type aliases to end-users

[SamChou19815]

Motivation

In #2578, I migrated all @docusaurus/core to TypeScript. During the migration, I have to declare modules to make TypeScript understand docusaurus-specific webpack aliases like @generated @theme. I put those declarations in a types.d.ts file inside @docusaurus/core.

In order to provide better TypeScript support for end-users, these aliases information also has to be available externally. TypeScript won't scan all node_modules to find this types.d.ts. Therefore, we need a way to tell to TypeScript to find the module declaration file.

My solution is to use the <reference types=... /> triple-slash directive. I moved the module declaration to a new package @docusaurus/module-type-aliases, and put

/// <reference types="@docusaurus/module-type-aliases" />

in place of the original types.d.ts.

Then once we published @docusaurus/module-type-aliases, An end-user can install it and add a file docusaurus.d.ts to their root with content /// <reference types="@docusaurus/module-type-aliases" />, then all the red-squiggly line under @theme, @generated will be gone! User doesn't need to go through the hack mentioned in #2578 (comment).

(This is the same approach taken by create-teact-app. It declares the css modules here, and link it in package.json here, and it will generate a react-app-env.d.ts with /// <reference types="react-scripts" /> in user's project folder).

Note

You might wonder why I didn't put the declarations in @docusaurus/types. In fact, this is the first thing I tried. However, it doesn't work well to mix module declaration and type definition together in one file, so I have to separate these two packages.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Everything still compiles and the preview site still works, which shows that this diff doesn't break anything.

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 de83513

https://deploy-preview-2608--docusaurus-2.netlify.app

[fanny]

Awesome, @samchan256! I didn't know a lot of typescript, but following your create react app references it seems great!

[yangshun]

This is great, thank you! Do we need to add docs about this?