Combine types into single file

[slevithan]

6 added TypeScript .d.ts files. However, multiple .d.ts files are currently generated. It would be nicer to generate a single file index.d.ts. PRs (or any other help) would be welcome from someone who wants to take on this issue. I'd be fine with switching from esbuild to another bundler if that helps keep things simple.

@rauschma asked about how to do this in this Mastodon thread. Saving the post and replies below for posterity.

Axel Rauschmayer:

TypeScript via JSDoc—the following works but produces multiple .d.ts files (only index.js is in the package exports, so a single .d.ts file would be better):

tsc src/index.js --rootDir src --declaration --allowJs --emitDeclarationOnly --outdir types

If I do --outfile index.d.ts (vs. --outdir) then I do get a single file but each module now has its own namespace which doesn’t go well with package exports.

Jon Koops: Not sure if it fits the bill exactly but https://tsup.egoist.dev/?

thurti: I had the same problem recently. I looked at how others do it (svelte) and ended up writing a script that bundles the d.ts files. Something like https://github.com/TranscribeJs/transcribe.js/blob/main/scripts/bundle-types.js

Nicholas C. Zakas: There is a Rollup plugin that combines .d.ts files. Though these days I usually Rollup the JS into a single file and then run tsc on the bundle file to avoid the mess.

Note: The Rollup plugin is probably referring to rollup-plugin-dts.

amsyar: https://github.com/timocov/dts-bundle-generator

[slevithan]

@nzakas's comment/suggestion about bundling the JS and then running tsc on the bundle is probably the way to go, but alas, regex currently uses esbuild for bundling, and esbuild doesn't (and won't) include an option to preserve JSDoc comments or all comments. So this would require switching to Rollup or another bundler, which I'm open to doing.

[rauschma]

My take – you can afford to wait:

• The current setup is reasonably elegant and easy to understand (which I personally find very important).
• .d.ts files are only used during development.
• A lot is happening in the TypeScript world at the moment: isolated declarations, a proposal for JS type annotations, TS support in Node.js, Deno’s JSR package registry, etc.
• You mentioned you might switch to TypeScript source – which would also change things (in many ways that’s actually easier than writing types in JSDoc comments).

[slevithan]

Based on @rauschma comment, I'ma go ahead and close this with no changes planned for now.

I've noticed that the plasmic library is currently relying on importing regex's types/pattern.d.ts, so any changes to the current approach of generating multiple .d.ts files would need to be treated as a breaking change.