feat(v2): Provide blog plugin theme typing #3267
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Deploy preview for docusaurus-2 ready! Built with commit 6757b48 |
slorber
reviewed
Aug 17, 2020
slorber
reviewed
Aug 17, 2020
slorber
reviewed
Aug 17, 2020
slorber
reviewed
Aug 17, 2020
|
Thanks, yes that looks like a good starting point. |
This was referenced Aug 18, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Although our classic-theme is written in TS, readers of the source code still can't easily see what's the prop types of each theme component. This is because we rely on the webpack alias
@theme, which makes typing difficult to enforce, even on TS sources.In the past, the best we can do is to add a catch all
@theme/*declaration in https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-module-type-aliases/src/index.d.ts. It makes writing theme code in TS a much better experience because there is no longer red squiggles, but the types are allany, which is not good for catching bugs.I think it's debatable whether we should provide typing information to all classic theme components, since some of them are considered as implementation detail. However, I think we should at least provide some typing information for some theme components expected by the plugins, since they are part of the public APIs exposed by a plugin and would be relied upon by third-party plugins. I think we should not throw these typing info into
@docusaurus/module-type-aliases, because it's designed to be more general purposed. Docusaurus core shouldn't care about the plugin-specific theme components; instead, it's the plugin packages' job to define those.Therefore, I decided to start with the blog plugin, which has a relatively simple interface. I defined the types in the
index.d.tsin the blog plugin and make the classic theme reference it. Then the classic theme can at least import the type definition ofPropsand use it for better typing. I think it's a good starting point to fully statically type the classic-theme.Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
It still compiles, which shows that the typing information is accurate enough for our purposes. Preview works.
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.)