# Pré-publicação

napi pre-publish (também disponível como napi prepublish) prepara e publica os pacotes de cada plataforma usando a versão atual do pacote raiz. Ele também pode criar uma release no GitHub e enviar os binários nativos como assets.

O comando não coleta nem copia artefatos de build. Execute napi artifacts antes.

# Uso

napi pre-publish [--options]

import { NapiCli } from '@napi-rs/cli'

await new NapiCli().prePublish({
  tagStyle: 'npm',
  ghRelease: true,
})

Opções booleanas aceitam o prefixo --no-. Por exemplo, use --no-gh-release quando a release não for executada no GitHub.

# Opções

# Efeitos colaterais exatos

Sem --dry-run, o comando executa estas etapas em ordem:

1. Lê o pacote raiz e a configuração napi.
2. Define a version de cada pacote de plataforma configurado como a versão raiz.
3. Mescla em optionalDependencies do pacote raiz uma entrada de versão exata para cada pacote de plataforma configurado. Entradas existentes são preservadas, inclusive pacotes de targets obsoletos.
4. Com releases GitHub habilitadas, resolve os metadados pelo último commit Git e por GITHUB_REPOSITORY; então cria a release, a menos que --gh-release-id escolha uma existente.
5. Para cada target cujo arquivo .node ou .wasm esperado exista no diretório npm, executa <npmClient> publish, salvo se --skip-optional-publish estiver definido.
6. Com releases GitHub habilitadas, envia o arquivo do target como asset.

Um arquivo esperado ausente gera um aviso e é ignorado; isso não encerra o comando com erro. Falhas ao criar releases ou enviar assets são registradas e podem não impedir a publicação npm. Portanto, a CI deve verificar por conta própria o conjunto completo de artefatos e o estado externo final.

napi pre-publish nunca publica o pacote raiz. No template gerado, ele roda em prepublishOnly; quando termina com sucesso, a operação npm publish ao redor dele publica o pacote raiz.

# Estado exigido para a release

Antes de executar com credenciais reais, confirme todos os itens:

• A versão do package.json raiz é final e nunca foi publicada.
• repository aponta para o repositório GitHub real. A proveniência npm valida a identidade do repositório e do workflow.
• napi.targets contém exatamente os pacotes destinados a esta release.
• As optionalDependencies existentes foram revisadas. O comando adiciona ou atualiza targets configurados, mas não remove entradas de plataforma obsoletas.
• napi create-npm-dirs criou cada pacote de target.
• napi artifacts colocou cada binário esperado tanto no pacote do target quanto no workspace raiz.
• Cada target passou em um teste de runtime no ambiente que declara suportar.
• O cliente npm configurado está autenticado para o pacote raiz e todos os pacotes de target.
• GITHUB_TOKEN, GITHUB_REPOSITORY e contents: write estão disponíveis quando releases GitHub estão habilitadas.
• O workflow tem id-token: write e a proveniência npm está habilitada quando se espera que a release inclua proveniência.

No workflow de pacote único gerado, use o estilo de tag npm:

{
  "scripts": {
    "prepublishOnly": "napi prepublish -t npm"
  }
}

O estilo lerna padrão serve apenas para um commit de release do Lerna cujo corpo liste a tag do pacote que será publicado.

# Faça uma prévia com segurança

Execute diretamente o modo dry-run do comando:

DEBUG=napi:* yarn napi prepublish -t npm --dry-run

Isso confirma que a configuração e os metadados da release Git podem ser lidos, mas não verifica a presença dos binários nem testa a autorização do registry.

Para inspecionar o tarball npm sem disparar o script prepublishOnly real, desabilite explicitamente os scripts de ciclo de vida:

npm pack --dry-run --ignore-scripts

# Falha parcial e recuperação

A release não é transacional. O npm não permite sobrescrever uma combinação de nome e versão publicada, e este comando não pode reverter pacotes já existentes.

Se uma execução falhar:

1. Interrompa tentativas automáticas até saber quais pacotes e assets existem.
2. Verifique cada target com npm view <package>@<version> version, confira o pacote raiz separadamente e inspecione os assets da release no GitHub.
3. Mantenha os mesmos artefatos de build. Nunca publique bits diferentes sob uma versão que já exista para outro target.
4. Execute novamente a mesma versão para publicar os targets ausentes. A CLI reconhece o erro padrão do npm para versões já publicadas e ignora esses pacotes; outros erros do registry ainda fazem a execução falhar.
5. Passe --gh-release-id <id> para reutilizar uma release GitHub existente ou --no-gh-release se os assets forem gerenciados em outro lugar.
6. Use --skip-optional-publish somente depois de confirmar que todos os pacotes de plataforma existem. A opção não valida essa condição.

Se todos os pacotes de plataforma existirem, mas a publicação raiz falhar, publique o tarball raiz inalterado a partir do job confiável com scripts de ciclo de vida desabilitados, por exemplo npm publish --ignore-scripts --access public. Preserve a mesma configuração de proveniência. Se o pacote raiz já foi publicado enquanto um pacote de plataforma está ausente, publique o pacote faltante imediatamente ou descontinue a versão raiz quebrada; o npm não oferece rollback atômico.

Consulte Publicar pacotes nativos para o runbook completo de CI.