refactor: improve setup of type declaration files #5914
Conversation
Josh-Cena
added
the
pr: maintenance
|
✔️ [V2] 🔨 Explore the source changes: f3a4c62 🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/618b12dc2b3e190007abcb80 😎 Browse the preview: https://deploy-preview-5914--docusaurus-2.netlify.app |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-5914--docusaurus-2.netlify.app/ |
|
Size Change: -185 B (0%) Total Size: 881 kB
ℹ️ View Unchanged
|
| } | ||
|
|
||
| // TODO public api surface types should rather be exposed as "@docusaurus/plugin-content-docs" | ||
| declare module '@docusaurus/plugin-content-docs-types' { |
There was a problem hiding this comment.
Not sure if merging '@docusaurus/plugin-content-docs-types' with '@docusaurus/plugin-content-docs' has deeper implications (e.g. implying that these types are public API while they can be breaking), but IMO type-related changes are never breaking changes as they can be easily ignored and TS-users are generally more aware of tech-related stuff anyways
There was a problem hiding this comment.
That should be fine, as we don't document this '@docusaurus/plugin-content-docs-types' anywhere afaik.
(but otherwise TS changes are to be considered as breaking changes too)
There was a problem hiding this comment.
Thanks, LGTM and looks cleaner 👍
Was wondering if you can find a way to preserve the Git history of packages/docusaurus-theme-classic/src/types.d.ts ?
It's a large file with some useful history context and Git currently understands it as a del+add instead of a move
| } | ||
|
|
||
| // TODO public api surface types should rather be exposed as "@docusaurus/plugin-content-docs" | ||
| declare module '@docusaurus/plugin-content-docs-types' { |
There was a problem hiding this comment.
That should be fine, as we don't document this '@docusaurus/plugin-content-docs-types' anywhere afaik.
(but otherwise TS changes are to be considered as breaking changes too)
|
I don't know why GH doesn't resolve the diff🧐 Beware though that even if it's resolved as a rename / mv, after merging git will treat it as a new file. e.g. https://github.com/facebook/docusaurus/blob/main/packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures.tsx only has one contributor because it was renamed |
Motivation
There are three types of declaration files:
<name>.d.ts, which contains the exported types used withimport xxx from '@docusaurus/<name>'or/// <reference types="@docusaurus/<name>" />(I think it actually makes sense to further separate them, but not right now);types.d.ts, types that should be globally available within the package (yet aren't exported). Commonly includes the module aliases, but in the future we can merge thetypes.tsidiom in here so we don't have the cluttering ofimport xxx from './types'everywheredeps.d.ts, types for missing dependency types, may be gradually removed in the future when types are available / we move to other depsHave you read the Contributing Guidelines on pull requests?
Yes
Test Plan
Build & typecheck