Tudo que bloqueou ao publicar @hsblabs/web-stream-extras no npm

Quando npm publish passou, foi uma boa sensação.

Os problemas vieram depois. Assim que migrei para o GitHub Actions, três coisas quebraram. A configuração do Trusted Publisher, os metadados relacionados a provenance e a ordem de tags e versões—cada um falhou por um motivo diferente, em um lugar diferente.

Estou documentando isso para que a próxima pessoa não perca o mesmo tempo.

Por que quis publicar o pacote

@hsblabs/web-stream-extras é um pacote pequeno de utilitários em torno da Web Streams API. Escrito inicialmente para reutilização interna, decidi torná-lo open source por ser genérico o suficiente.

Por que publiquei 0.0.1 manualmente a partir do local

Na primeira versão, executei npm publish localmente antes de configurar o Actions. O objetivo era confirmar que install e import funcionam depois que o pacote está no npm. Deixei a infraestrutura de release para depois—configurar automação antes que as coisas estejam estáveis só adiciona mais uma camada de depuração.

Há outro motivo. Para configurar o Trusted Publisher no lado do npmjs, o pacote já precisa existir no npm. Ou seja, a primeira publicação tem que acontecer de alguma outra forma. Sem isso, não há como acessar a tela de configuração.

Migração para GitHub Actions + Trusted Publisher no 0.1.0

A publicação manual ficou em uma única vez, e tudo depois passou a ser feito via GitHub Actions.

O Trusted Publisher do npm permite publicar via OIDC sem emitir ou gerenciar tokens. Ele usa um token de curta duração gerado pelo workflow, então não há necessidade de armazenar NPM_TOKEN como secret.

A configuração tem dois pontos centrais. No lado do npm, especifica-se o nome do arquivo de workflow ao adicionar um Trusted Publisher. No lado do GitHub Actions, adiciona-se a permissão id-token: write e remove-se NODE_AUTH_TOKEN.

permissions:
  id-token: write
  contents: read

Deixar NODE_AUTH_TOKEN no lugar pode fazer o fluxo OIDC do Trusted Publisher falhar. Instruções baseadas em token que ainda estão no README ou em TODOs vão causar confusão—o melhor é limpar tudo durante a migração.

Falhas que realmente aconteceram

Publicação parando com 422 Unprocessable Entity

Apenas o step de publicação no Actions estava falhando. O erro era 422 Unprocessable Entity. Todo o resto passava, então no início eu não tinha ideia de onde procurar.

A causa foi repository.url vazio no package.json. Quando provenance está ativado, o npm usa repository.url para vincular o pacote ao seu repositório. Se esse campo estiver ausente, a resposta é um 422.

// antes
"repository": {}

// depois
"repository": {
  "type": "git",
  "url": "https://github.com/hsblabs/web-stream-extras"
}

Mesmo verificando todos os outros metadados, esse campo é fácil de deixar passar.

Ordem do tag e de package.json.version

O workflow valida que o nome do tag corresponde a package.json.version.

Se o tag for criado antes de atualizar a versão, a validação falha. A ordem correta:

1. Atualizar package.json.version e commitar
2. Taggear esse commit
3. Fazer push

Se a ordem for invertida, a versão no commit apontado pelo tag não vai corresponder ao nome do tag. Se falhar, basta deletar o tag e recriar.

git tag -d v0.1.0
git push origin :refs/tags/v0.1.0
# depois do commit com a atualização de versão
git tag v0.1.0
git push origin v0.1.0

O fluxo de release que finalmente se estabilizou

Veja como funciona agora:

1. Implementar e testar
2. Atualizar package.json.version e commitar
3. Fazer push de um tag v{version}
4. O Actions detecta o push do tag e executa a publicação

A validação pré-publicação está consolidada no comando publish:check—lint e verificações de tipo sem --write. Colocar essa etapa antes da publicação evita que mudanças não commitadas se infiltrem. Encadear comandos de auto-correção diretamente pode criar mudanças não commitadas bem antes da publicação, o que vale a pena ter em mente.

Também rodei pnpm pack --dry-run para inspecionar o conteúdo do tarball. Mesmo com files apontando apenas para dist/, sourcemaps podem acabar lá dentro. Se não quiser publicá-los, excluí-los no lado do build é a abordagem mais segura.

O que quero melhorar a seguir

Quero integrar a geração automática de changelog ao fluxo. Por enquanto é manual, e algo sempre escapa cada vez que crio um tag.

Os passos para migrar de publicação manual para Actions são simples. As dificuldades estão nos detalhes de configuração. O Trusted Publisher elimina a necessidade de gerenciar tokens, mas exige que as configurações de OIDC estejam alinhadas com precisão. Confirmar que o lado do npm e o lado do Actions se correspondem um a um antes de executar qualquer coisa é o caminho mais rápido.