feat: properly type-check the Docusaurus config of new sites

[bmiddha]

PR created by @bmiddha, completed by @slorber

Motivation

• Introduce new types for user-provided Config, ThemeConfig and plugin Options (raw, unnormalized types)
• Make Config consistent with API reference and expectations.
• Add // @ts-check for all new sites (+ Docusaurus site)
• Docusaurus site should typecheck its config in CI and watch mode
• Fix existing site typecheck issues that were previously unreported
• Make Config consistent with API reference and expectations.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Site config errors should be reported on yarn workspace website typecheck

CI should pass, ensuring our own site config is valid

Related Issues

closes #5588

[Josh-Cena]

Remember there are two configs: one user-provided, and one after Joi normalization. The code expects the one after normalization where all these keys actually exist, therefore the current fix doesn't work. I think a more sensible fix is to provide another UserDocusaurusConfig type? In fact the same thing happens for Navbar and Footer configs, preventing me from writing my config in TS

[bmiddha]

I like the UserDocusaurusConfig idea.
Something like this perhaps?

export interface UserDocusaurusConfig extends Partial<DocusaurusConfig> {
  baseUrl: string;
  url: string;
  title: string;
}

[Josh-Cena]

That looks good to me. Are you sure the required fields include and only include these keys?🧐

[bmiddha]

Seems like it. I based that from the docusaurus.config.js reference.
From a brief look at packages\docusaurus\src\server\configValidation.ts, baseUrl title, and url should be the minimum config required.

[netlify]

✔️ [V2]

🔨 Explore the source changes: 0538186

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/6155d6e2556ccf000841173c

😎 Browse the preview: https://deploy-preview-5589--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	90
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5589--docusaurus-2.netlify.app/

[slorber]

UserDocusaurusConfig is nice but this is public API surface that we should also add in our doc and init templates JSDoc annotations.

Isn't it confusing to for users to have UserDocusaurusConfig (in config) + DocusaurusConfig (in code, pages etc...)?

There are other naming possibilities like DocusaurusConfig + DocusaurusConfigNormalized, which is better?

Is there another better alternative?

Since this is a regular pattern to have partial user inputs that get normalized, we should find and stick to a shared convention for type names, particularly when they are documented as public API like in this case.

[Josh-Cena]

Isn't it confusing to for users to have UserDocusaurusConfig (in config) + DocusaurusConfig (in code, pages etc...)?

Not many users use the DocusaurusConfig type explicitly, unless there are use-cases I didn't think of.

There are other naming possibilities like DocusaurusConfig + DocusaurusConfigNormalized, which is better?

DocusaurusConfigNormalized is too long even for an internal type, I'd rather want to save a few keystrokes.

Not saying UserDocusaurusConfig is a good name, but just some thoughts

[slorber]

Not many users use the DocusaurusConfig type explicitly, unless there are use-cases I didn't think of.

It's in the JSDoc template so it's in a few newly initialized sites already

I'm fine with UserDocusaurusConfig, I don't have better either 🤪 naming is hard

[Josh-Cena]

It's in the JSDoc template so it's in a few newly initialized sites already

I meant the actual DocusaurusConfig with more required fields than UserDocusaurusConfig :P If we only expose UserDocusaurusConfig there won't be much confusion, although the name is kind of weird on its own

[slorber]

DocusaurusConfig type will remain exposed because it's provided as props and useDocusaurusContext() return anyway, so both are part of the public AP. For TS sites, users may need to import both types, that's why we should try to make things not too confusing 🤪

[slorber]

FYI I used the export Config: it will be a simpler export name and be consistent with Options and ThemeConfig.

Using User prefix everywhere is a bit heavy from a public API perspective, I'd rather have a Docusaurus prefix for the normalized version

[slorber]

PR is ready for me and we have better config typechecking running in our CI now

Just not sure why some Prettier changes merged recently are reverted 😅

[Josh-Cena]

For weird reasons my IDE still reformats the old way on save 😓

Could it be a local version incompatibility? I suppose you have run yarn install, so maybe you have an older version of Prettier installed globally? (Don't know how Idea does the formatting)

[slorber]

After restarting Intellij, it seems fixed :)