.d.ts bundles

[aleclarson]

Current Behavior

Every module has its own .d.ts module

Desired Behavior

Bundle the typedefs into a single .d.ts module

Suggested Solution

https://www.npmjs.com/package/rollup-plugin-dts

[swyxio]

just for learning's sake what would be the benefit of bundling everything in 1 .d.ts vs all separate?

[aleclarson]

Cleaner dist/ folder, I guess. And it better mirrors the fact that the source code is bundled. Definitely just a "nice to have".

[aleclarson]

Oh boy! Here's a library that doesn't require Rollup (not sure if that's better or worse in the case of tsdx): https://github.com/timocov/dts-bundle-generator

[jaredpalmer]

Yeah this would be cool. Seems experimental though?

[aleclarson]

I'm trying it on react-spring in a little bit. We'll see how it goes. Would definitely be an opt-in feature in tsdx.

[aleclarson]

Both rollup-plugin-dts and dts-bundle-generator include types from imported node_modules in the output bundle, which is probably not what we want. According to this comment, the @microsoft/api-extractor package does not do that.

More details: https://api-extractor.com/pages/setup/configure_rollup/

cc @timocov @Swatinem

[timocov]

Both rollup-plugin-dts and dts-bundle-generator include types from imported node_modules in the output bundle, which is probably not what we want.

@aleclarson can you please show how did you test it? Afaik by default dts-bundle-generator treats node_modules as external folder and shouldn't include anything from it (except imports).

[Swatinem]

Both rollup-plugin-dts and dts-bundle-generator include types from imported node_modules in the output bundle, which is probably not what we want.

Since rollup-plugin-dts is based on rollup, you have to configure it accordingly, which in this case means you need to add everything to external that you don’t want to put into the bundle.

[aleclarson]

@timocov @Swatinem Thanks for the info! I would definitely prefer using one of your libraries, since API Extractor has awful configuration requirements.

This is what I used to get API Extractor working:

{
  "mainEntryPointFilePath": "<projectFolder>/types/index.d.ts",
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/index.d.ts"
  },
  "docModel": {
    "enabled": false
  },
  "apiReport": {
    "enabled": false
  },
  "messages": {
    "extractorMessageReporting": {
      "ae-missing-release-tag": {
        "logLevel": "none"
      }
    }
  }
}

@timocov I've only tried rollup-plugin-dts, but your comment led me to believe dts-bundle-generator worked the same way. Thanks for clarifying!

3. It looks like api-extractor requires you export all interfaces/functions/const/etc from your entry point if you want to export them, and doesn't follow dependencies, right? If so, this is difference also, because dts-bundle-generator will follow dependencies and put them all into result file.

[timocov]

will follow dependencies and put them all into result file.

Dependencies from local files of course. All external deps it'll import/or add via triple-slash directive (depends on where typings are) by default, but what should be imported/inlinded can be changed via CLI args (or config file).

[aleclarson]

This is an overview of .d.ts bundlers that I've tried to use with Rollup.

rollup-plugin-dts

• 🎉 Easily plugs into Rollup
• 🎉 No notable issues?

dts-bundle-generator

• 👎 Dependencies must have .d.ts modules or an associated @types package
• 👎 Must write your own Rollup plugin

dts-generator

• 😑 Emits a declare module statement for every .ts module
• 👎 Must write your own Rollup plugin

@microsoft/api-extractor

• 👎 Must use intermediate .d.ts modules
• 👎 Verbose configuration
• 👎 Must write your own Rollup plugin

[timocov]

@aleclarson great job 👍!

Dependencies must have .d.ts modules or an associated @types package

Does it related to timocov/dts-bundle-generator#53? I'm not sure how it will even work, because afaik TypeScript compiler doesn't compile source files from node_modules.

[aleclarson]

Now that Swatinem/rollup-plugin-dts#32 is merged, my needs are satisfied by rollup-plugin-dts and I would recommend it for tsdx too. 👍

[phryneas]

I would very much appreciate something like this - right now, I can't import anything from any .d.ts file except from the index.d.ts - as they don't have accompanying .js/.ts files and webpack refuses to import where only a .d.ts exists, but no file with a webpack-configured extension.

Re-exporting everything I need from the index.js/.d.ts on the other hand does not play well with babel-preset-typescript as that doesn't support re-exporting types.

So currently, I'm renaming all .d.ts post-build from .d.ts to .ts for babel-loader and webpack to recognize them. And that certainly isn't the "right" way :/

[swyxio]

we had some churn with v0.10 but now are back to separate .d.ts - if anyone wants to explore rollup-plugin-dts or any other solutions please have a try

[smashercosmo]

Just quickly tested rollup-plugin-dts with tsdx and unfortunately it didn't work out of the box. Got TypeError: Cannot read property 'getText' of undefined error. Will try to investigate. But if you have any ideas on what's going on, please share.

[Swatinem]

Got TypeError: Cannot read property 'getText' of undefined error. Will try to investigate.

That is definitely a bug in my library. Would very much appreciate an issue report with a reduced testcase.

[smashercosmo]

@Swatinem I tried to create a small example to demonstrate the issue. I started with a clean tsdx project. Added test.ts file in addition to index.ts. Added rollup-plugin-dts and run build. I didn't get any TypeError, but I also didn't get a result I was expecting to get. I was expecting to get single .d.ts bundle with all the types, but instead got two separate files: index.d.ts and test.d.ts. Is it another bug or I'm doing something wrong? Here is my test project https://github.com/smashercosmo/rollup-plugin-dts-issue

[Swatinem]

@smashercosmo

I was expecting to get single .d.ts bundle with all the types, but instead got two separate files: index.d.ts and test.d.ts.

Hm, it doesn’t seem the plugin is actually invoked? No idea. I just pasted your code into the plugin testsuite, and it ran fine.

[zenflow]

@aleclarson In response to #80 (comment): API Extractor doesn't just solve this (.d.ts bundles issues).. it also generates API documentation & API reports (for PR process).. that should count for a lot!

Another note about API extractor, regarding "Must write your own Rollup plugin". Here's some work that's been done on this: https://github.com/rocketbase-io/rollup-plugin-api-extractor It looks pretty simply/straightforward. We could easily include this plugin functionality in tsdx, do the .d.ts bundling by default, and add expose some new options for generating API documentation and reports. Couldn't we?