Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

Clarifying recommendation for when to publish types to DefinitelyTyped vs bundled

Aberta
  • Algo errado?
#2,805 3 comentários 1 reação 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
2/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
45/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Estagnada
Stack de tecnologia
typescript
Domínio
documentation

Direção de pesquisa

Comece por packages/documentation/copy/en/declaration-files/Publishing.md, especialmente pelas orientações em torno das linhas 11–16, e compare a redação delas com o esclarecimento proposto na issue. Considera-se concluído quando a documentação distinguir claramente entre tipos incluídos e as orientações do DefinitelyTyped para projetos TypeScript e JavaScript.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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:

  • Source is not in TypeScript. Code maintainer willing to add, maintain, and publish type definitions alongside source.

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.

Linguagem predominante
TypeScript
Estrelas
2.6k
Forks
1.5k
Merge médio
2d 12h
PRs com merge (30d)
8

Preparar o ambiente

Ainda não verificamos os arquivos de configuração deste projeto. Comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de microsoft/TypeScript-Website

Todas as issues de microsoft/TypeScript-Website

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.