? Escreva e publique um código mínimo

Para publicar uma biblioteca no npm, você precisará de:

1. Uma conta npm; você pode se inscrever aqui.

2. Seu código como um projeto; ou seja, você tem um package.json em seu diretório de código, que tem nome e versão especificados. Observe que você pode gerar este arquivo via:
   

npm init

1. Um index.js em seu projeto. Lembre-se, você precisa exportar sua função para permitir que os usuários a importem.

Nota: Se o seu script não for nomeado index.js e colocado na raiz do projeto, você precisará especificar a propriedade "main" em package.json. Veja esta resposta para mais informações.

E se o nome foi usado no npm, você pode adicionar um prefixo como @name-or-org/your-lib; isso é o que a maioria das outras bibliotecas fazem hoje em dia.

Você pode verificar meu exemplo mínimo para referência, mas acredito que você pode escrever algo mais legal do que isso.

Finalmente, publique-o com o comando CLI:

npm publish

Nota para as pessoas que definem o nome do pacote com um prefixo: Ele DEVE ser seu nome de usuário npm ou nome da organização que você registrou no npm. Por exemplo, posso usar @remi_guan como meu prefixo, mas não outros.

Além disso, você precisa executar npm subscribe --access public, porque o npm acha que você deseja publicar um pacote privado, que é um recurso pago.

Esta saída significa que foi bem-sucedido. No entanto, se você tiver algum problema, poderá pesquisar no Google para solucionar o problema. E aqui está como você pode usar sua própria biblioteca:

Se você tem seguido este guia, experimente sua própria biblioteca.

Também descobri que @backendbro tem um guia muito detalhado do que este, se você quiser saber mais.

Depois de publicar seu código, quando quiser atualizá-lo, você pode executar o npm subscribe novamente. No entanto, antes de publicar, você deve atualizar a propriedade version de package.json e cumprir o Versionamento Semântico.

Eu sugiro que você experimente! Você pode publicar a versão 1.0.1 ou v1.1.0 da sua biblioteca e usá-la em outro projeto como o que acabei de fazer? Você consegue descobrir como atualizar a versão da sua biblioteca npm?

? Usar TypeScript

Esta biblioteca que criamos até agora não é moderna, falta declaração de tipo para que as pessoas que usam sua biblioteca não possam ser destacadas com a digitação. Além disso, as pessoas costumam usar TypeScript com sintaxe ECMAScript. Para saber mais sobre a diferença: Módulos Node.js: CommonJS vs. ECMAScript por Saisathish

Mas vou pular a configuração detalhada do TypeScript nesta postagem. Existem muitos tutoriais bons para aprender como inicializar um projeto TypeScript, como “Como desenvolver uma biblioteca TypeScript” por inapeace0.

Ainda mais, você pode usar um modelo de repositório TypeScript como alexjoverm/typescript-library-starter que já integrou muitas ferramentas modernas, práticas recomendadas, etc.

Vou apenas mencionar algumas notas importantes se você estiver publicando uma biblioteca TypeScript:

1. Compile antes de publicar. Se você precisar publicá-lo ao público, pessoas com o ambiente Node.js mais comum só poderão executar arquivos .js. Então você precisa compilar seu código com tsc, rollup (ou vite, que usa rollup) ou webpack; qualquer um está bem.

Você precisa apontar corretamente para o arquivo compilado usando as propriedades module, main ou input em package.json. Usar um modelo e aprendê-los um por um é uma boa escolha. Novamente, alexjoverm/typescript-library-starter os especificou muito bem.

1. Inclua um arquivo .d.ts. Pelo mesmo motivo, o usuário também precisa de acesso às assinaturas de tipo.

Mas se você tem certeza de que sua biblioteca será executada em Deno, Bun ou ts-node, você pode ignorar minhas diretrizes acima porque elas suportam a execução nativa de código TypeScript.

Tente seguir um guia para criar uma biblioteca TypeScript e publicá-la no npm. Ainda é fácil, como no primeiro exemplo. Você deve testá-lo com outro projeto usando sintaxe de importação e poderá ver dicas de tipo com um IDE.

Com TypeScript, posso escrever minha biblioteca nesta sintaxe:

E depois de publicar, posso instalá-lo e importá-lo, e ver as dicas de tipo graças ao TypeScript.

✨ Versionamento Semântico

Há um problema comum, mas um pouco avançado, esperando para ser resolvido: cada vez que atualizamos nosso pacote, precisamos editar o código da versão.

Isso é irritante, especialmente se você atualiza seu código com frequência.

No entanto, existem ferramentas para ajudá-lo.

• liberação semântica: Totalmente automática; você pode integrá-lo ao GitHub CI para atualizar automaticamente o código da versão e publicar no npm sempre que atualizar seu código no GitHub.
• release-it: Também ajuda a melhorar a versão, mas é simples de usar (não há necessidade de conhecimento de CI); enquanto isso, você não o configura como totalmente automatizado.

Usei o ChatGPT para gerar este resumo comparando as duas ferramentas. Para novos programadores, sugiro que você experimente o release-it, mas o lançamento semântico também é conveniente se você souber como integrá-lo ao CI.

Neste post vou mostrar como usar o release-it, bem, depois de fazer as alterações no projeto, basta executar isto no seu projeto:

npx release-it

E escolha se é uma pequena alteração ou uma grande alteração, então pronto!

Resumo

Então aí está! Percorremos a publicação de uma biblioteca npm simples, a atualização e até mesmo o uso do TypeScript para torná-la mais moderna e robusta. Lembre-se de:

• Exporte suas funções corretamente para que outras pessoas possam usá-las.
• Atualize seus números de versão seguindo o Versionamento Semântico.
• Considere usar TypeScript para melhor segurança de digitação e experiência do desenvolvedor.
• Automatize seus lançamentos com ferramentas como release-it ou semantic-release para economizar tempo.

Experimente! Publique sua própria biblioteca, atualize-a e veja como é contribuir com o ecossistema npm. Boa codificação!