Leverage TypeScript project references

[remcohaszing]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

This changes the TypeScript configuration of the project. It’s based on https://github.com/orgs/unifiedjs/discussions/238. The project now uses 2 TypeScript configurations: tsconfig.json and tsconfig.build.json. There’s also tsconfig.base.json. This is an implementation detail, it only exists so it can be extended from.

tsconfig.build.json is used to build the source files.

• It only includes the lib directory.
• It emits the type declarations into the types directory.
• It does not include the node types, meaning that importing Node.js builtins will cause the build to fail.
• It includes the dom lib, which is needed because of an upstream dependency.
• It does not allow the use of JSX.
• It includes a new file lib/exports.ts, which can be used to re-export additional types. This replaces the old index.js in the project root, which @typedef tags to mimic type exports.

tsconfig.json is used to typecheck the rest of the project.

• It excludes the lib directory.
• It does not emit type declarations.
• It includes the node types, meaning we can import Node.js builtins (such as node:test)
• It does not include the dom types, meaning we can’t use browser globals there.
• It builds tsconfig.build.json first, based on references.
• It type checks the types directory emitted by tsconfig.build.json. We have run into JSDoc specific emit issues before, so this is really nice to have.

To build or rebuild the project, we can now run either tsc --build or tsc --build --force. This correctly uses incremental builds, so a second run of tsc --build is faster.

Without this PR, after building, we have type errors in our editor. This is now solved.

Variations of this are possible. The main point is:

• Separate JavaScript source files from other JavaScript files.
• Use separate configurations for different environments/purposes. This is even more apparent for mono repos that target different conflicting environments. (I have a commit ready for https://github.com/mdx-js/mdx, but wanted to discuss this in a simpler repo first.)
• Use rootDir and outDir.
• Avoid writing .d.ts files.
• Use .ts files to write TypeScript things that are not possible with types in JSDoc.

An interesting idea that builds on this, is to move type definitions from @typedef tags into TypeScript files.

[wooorm]

should be possible to do Markdown as default, then you don‘t need the change in lib/index.js here

[wooorm]

this change can be discarded, with the change in lib/exports.ts

[wooorm]

I think this should be an lib/export.d.ts, with a different lib/export.js focussing on the values.
The primary goal is to not use a proprietary closed-governance compile-to-javascript language. Having types is fine. But not at the cost of having to compile.
Secondary, compile-to-javascript(/types) languages in my experience are bad at compiling. We can get better code by writing them manually.
TS has been generating bad or slow d.ts types. I think we should write those ourselves.

[wooorm]

I think it’s sad that we can no longer have index.js, and have to resort to lib/exports.*.
An index.js in the root is useful when getting into a new project: you know it’s going to include the API. Now we don’t have that.

[wooorm]

Suggested change

	*.tsbuildinfo
	*.log
	*.log
	*.tsbuildinfo

[wooorm]

Is it correct that the types field here is only needed because you want to overwrite lib/index.d.ts, for consumers of 'react-markdown'?

[wooorm]

What does the generated folder structure look like?
I am not happy about the extra folder. Feels like this is patching a bug that TS should solve.