search

microsoft / TypeScript-Website

The Website and web infrastructure for learning TypeScript
https://www.typescriptlang.org
Creative Commons Attribution 4.0 International
2.17k stars 1.34k forks source link

Clarifying recommendation for when to publish types to DefinitelyTyped vs bundled #2805

Open cinderblock opened 1 year ago

cinderblock commented 1 year ago

Per #2804, I am creating a new issue to replace #2032 with renewed clarity and purpose.

When publishing types, there are essentially two standard ways to do so:

https://github.com/microsoft/TypeScript-Website/blob/b0e88bb679b78a6066e1734ffc22387550eaa8cf/packages/documentation/copy/en/declaration-files/Publishing.md?plain=1#L11-L16

Reading this, to me, "Otherwise" suggests that packages should only bundle their types if they were automatically generated.

This nicely covers two use cases:

  1. Source is in TypeScript. Published package is compiled to JavaScript alongside type definitions.
  2. Source is not in TypeScript. Package users independently publish and maintain types for the package.

I think a 3rd intermediate case is missing:

I've had passing conversations with maintainers that seemed to me to be under the impression that publishing manually created types separately was the preferred way to do it, seemingly because of this phrasing. Some even suggested doing this for TypeScript packages...

As far as I can tell, there is basically no downside to publishing accurate types along with source code, besides a marginal increase bundle size. The improved developer experience is well worth it and the types get compiled away for any real publishing. I would also think DefinitelyTyped would prefer if others did not rely on DT as it centralizes type issues in their respective packages and handles mismatched version issues intrinsically.

Suggestion for new phrasing

Including up-to-date types in published packages is always preferred. Bundling types improves developer experiences and reduces occurrence of common bugs and issues. If your types are generated by your source code, or you are keeping them up to date manually, we recommend you publish them with your published code bundle. Both TypeScript and JavaScript projects can generate types via declaration.

If you would prefer to not bundle your type definitions in your published package, we recommend submitting the types to DefinitelyTyped, which will publish them to the @types organization on npm.

If you do neither, any users of your package may still submit their own types to DefinitelyTyped.

jakebailey commented 1 year ago

I think the new wording is good; are you willing to send a PR to improve the docs?

cinderblock commented 1 year ago

Sure. Might not be able to get to it for a few days.

Any suggestions/changes are of course welcome!

andrewbranch commented 1 year ago

If you would prefer to not bundle your type definitions in your published package, we recommend submitting the types to DefinitelyTyped

I actually don’t want to imply that it’s really an option at all for a package owner to publish their package without types and then publish the types on DT. In the past, some people have chosen to do this in order to game the special treatment node_modules/@types gets as the default tsconfig types array.

Maybe just replace “would prefer to not” with “cannot”?