Typescript: Remove the suggestion recommending publishing to @types

[PandaWood]

The document page at https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

Suggests that if your project isn't TypeScript then publishing to the @types organization on npm is the preferred approach.

Search Terms

DefinitelyTyped
@types

Suggestion

This suggestion seems objectively wrong to me, and is not supported by anything other than the word "recommended"

I suggest either say why it's recommended or, preferably, replace it and suggest that publishing to @types organisation should always be avoided if there's a project that already exists to support it.

I don't know of any sound reason to support the current "recommendation" but I can think of many reasons not to ie Why would you:
1 - Break up a single project into 2 parts (typings/actual)
2 - Force users of the library to figure out and use 2 commands (actual + typings) to install a single library

Libraries like Vue js do as I suggested and remove their @types library after including it in their main project

Can anyone provide a sound reason why a project should be split into two, just for TypeScript typings, to support this recommendation?

[DanielRosenwasser]

I've also explained this on Twitter, but I'll try to fill in an answer here.

Glad you brought Vue up as an example. As a member of the TypeScript project, contributor to the Vue type declarations, and maintainer on DefinitelyTyped, I can confidently say that pushing library authors to ship .d.ts files is not a good idea.

First of all, when asking maintainers to put .d.ts files in their repo, those maintainers now have the burden of managing the publishing cadence for .d.ts files. While this is great for ensuring stability, it means that a .d.ts file change requires a new publish of the library, which is a hassle for library authors. In contrast, DefinitelyTyped has the types-publisher which automatically publishes a patch version on every change. It's not perfect, but it's worked decently for the community.

Next, library authors now also have to start understanding TypeScript or trust contributors. This simply doesn't work well because often an innocent-looking change makes its way into the repo and ends up being wrong. Users reporting these breaks will often confuse library authors, and I've actually seen library authors rip .d.ts files out of their repos out of frustration. And it's understandable. It's not fair to them. To contrast, DefinitelyTyped has (1) .d.ts file authors and (2) members of the TypeScript team doing some general overview to ensure that the declaration files appear correct.

Lastly, testablity is a major boon with DefinitelyTyped. The fact that DefinitelyTyped is a mono-repo has been extremely helpful in detecting the sort of impact a change will have. DefinitelyTyped also just has built-in infrastructure like dtslint (see Testing Types: An Introduction to dtslint).

[PandaWood]

Right, thanks for that.
Fair enough. So you disagree with VueJs decision to include the types or are there valid exceptions?

I have this from LinusBorg (core team member), which basically argues the opposite.

I think you misunderstand what @types from definitelytyped are for: that repository provides types for libraries that don’t already come with types in their npm package - one of those is, for example, lodash. The lodash author doesn’t provide any typings, so the community stepped up and added them to @types

[RyanCavanaugh]

I think that's a misunderstanding of what DT is for.

There's also the problem of versioning, which I know dojo is struggling with - they want to use the latest & greatest TypeScript features like conditional types, but don't want to drag forward all of their TS consumers to new TS versions just to get new dojo runtime features. DefinitelyTyped handles versioning for downlevel compilers automatically and allows the types version and runtime versions to float independently, which isn't really possible if you bundle types.

Anyway, if a library wants to opt in to managing these issues and is willing to do a good job, then it's 100% great for them to do that. In the past we recommended bundling, and too many packages that weren't able to manage the complexity of it jumped in without realizing what they were signing up for.

[PandaWood]

OK Thanks for your time.
I do agree with your points.
I've been schooled twice on this issue now ;-)

[ericmorand]

@RyanCavanaugh, isn't the DefinitelyTyped documentation saying the exact opposite of what you just explained?

If you are the library author and your package is written in TypeScript, bundle the autogenerated declaration files in your package instead of publishing to DefinitelyTyped.

https://github.com/DefinitelyTyped/DefinitelyTyped#create-a-new-package

[RyanCavanaugh]

There are pros and cons to both approaches. For most libraries written in TypeScript which have APIs that can be described with long-present syntax, which is really the majority, bundling the types is generally better. I think that sentence on DT is accurate enough given the context it's in.

[ericmorand]

You're totally right. I overlooked the fact that the recommendantion linked by @PandaWood is explictely saying "If your package is written in TypeScript then the first approach is favored" and "If your package is not written in TypeScript then the second is the preferred approach", second option being publishing on @types.

[ericmorand]

I just realized that having a separate project for typings can have interesting benefits for libraries that exposes interfaces.

Let's assume that I'm coding a huge library that exposes a plugin system backed by some interfaces - i.e PluginInterface.

If my library bundle the declaration files alongside the generated code, any plugin project would need to install the entire library just to be able to use the plugin interface. This could be quite an overkill since the library is assumed to be huge.

If my library also comes with a separate bundle that just include the declarations, then plugin project can just install this tiny package to use the plugin interface and compile succesfully.

[mhoeger]

@RyanCavanaugh and @DanielRosenwasser - do you have any thoughts on @ericmorand 's comment above about using a separate project for typings to expose interfaces? I'm wondering if I should do this.

The project I work on is not published on npm and is not useful to be published there. It's important to expose the TypeScript interfaces though. Since the project is written in TypeScript, we're torn on whether we want to publish just the typings as an npm package representing our project (using .npmignore to exclude actual code) or as an @types library.

Maybe this is just a judgement call, but would love your input!