feat: create official TypeScript base config @docusaurus/tsconfig

[slorber]

Breaking change

The old external @tsconfig/docusaurus package is now deprecated and you should use our new official versioned package @docusaurus/tsconfig.

The standard Docusaurus website TypeScript config becomes:

{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    "baseUrl": "."
  }
}

Motivation

Follow-up of the React 18 upgrade (#8961) including the usage of the automatic JSX runtime: we should now use jsx: "preserve" in our base default TS config

As discussed in the past: our base TS config should evolve alongside the codebase and be versioned (cf tsconfig/bases#122)

Test Plan

website + dogfood + CI

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

Automatic JSX runtime needs use to change the config to jsx: "preserve" instead of jsx: "react".
See also:

• feat: React 18 + automatic JSX runtime + build --dev #8961
• https://www.totaltypescript.com/react-refers-to-a-umd-global

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	b115a6f
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/648318f9e1c85d0007dbf5db
😎 Deploy Preview	https://deploy-preview-9050--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 86	🟢 97	🟢 92	🟢 100	🟠 89	Report
/docs/installation	🟠 77	🟢 100	🟢 92	🟢 100	🟠 89	Report

[github-actions]

Size Change: +64 B (0%)

Total Size: 1.04 MB

Filename	Size	Change
website/build/assets/js/main.********.js	784 kB	+64 B (0%)

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	101 kB
website/build/assets/css/styles.********.css	113 kB
website/build/index.html	40.9 kB

_{compressed-size-action}

[andrewbranch]

We are considering making it an error to specify moduleResolution: "node16" without "module": "node16" at microsoft/TypeScript#54567. "module": "node16" implies "moduleResolution": "node16", but unfortunately not the reverse. Using one without the other matching has some very strange, unpredictable, and dangerous effects.

Many of the new errors that we detected would occur from this change are in tsconfigs that inherit from the old @tsconfig/docusaurus package. Would you be able to add "module": "Node16" to this template?

[Josh-Cena]

The moduleResolution should be bundler, because this config is shared for our users, who exclusively write client code. We use "moduleResolution": "node16" here so that package.json exports can be resolved, but if we use "module": "node16", then because users never specify "type": "module" in their package.json (this actually breaks webpack, for some reason yet to be discovered), they will not be able to import ESM dependencies.

[andrewbranch]

Oh, can you change to module: esnext with moduleResolution: bundler, then?

[Josh-Cena]

Sure! I don't think anyone has played with the tsconfig since the last time I added node16. I'm a bit caught up with MDN work recently so I may not be able to come back to it, but I (or @slorber) will surely play with it when we have time.

[andrewbranch]

How do you version @docusaurus/tsconfig? Would this have to wait until a major version bump of other docusaurus packages?

[Josh-Cena]

@docusaurus/tsconfig is already created for the next major, so before its release, we are free to do anything with it :) Do you anticipate the switch to moduleResolution: bundler to be a breaking change?

[andrewbranch]

Technically it could introduce new TS errors. With node16 and no "type": "module", resolution of imports of external libraries uses the types, node, and require conditions when lookup up conditional exports, because the assumption is that these imports will be emitted as require calls (this is part of why mixing --moduleResolution node16 with --module esnext breaks some core assumptions in the compiler). With bundler, the conditions are types and import. This better matches what Webpack is actually going to do during its own resolution, but we do occasionally see external libraries that have messed up the types for their import entrypoint.

So, it’s really like a bugfix, but it could trigger an external library’s typing bug in a way that the current config doesn’t.

[Josh-Cena]

I see. It should be okay for us. Our versioning scheme typically allows "more type errors that are undeniably user bugs" across minor versions.

[slorber]

Hi @andrewbranch

Our CI started failing after 5.2 GA release, so it's a good reminder for me to handle this 😅

This will be fixed in #9258

Thanks