Como Criar e Publicar um Pacote npm

Você já instalou centenas de pacotes com npm install. Agora você quer publicar o seu próprio. O processo parece simples até você descobrir tutoriais desatualizados recomendando Node 12, configurações apenas com CommonJS e tokens de longa duração armazenados em secrets de CI.

Este guia orienta você na criação e publicação de um pacote npm usando práticas modernas e seguras que ainda estarão corretas em 2025. Vamos construir um utilitário simples, configurá-lo adequadamente e publicá-lo com npm Trusted Publishing.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Node.js 18 ou posterior instalado
• Uma conta no GitHub
• Familiaridade básica com npm como consumidor

Inicialize sua Configuração de Pacote npm ESM-First

Crie um novo diretório e inicialize seu projeto:

mkdir use-toggle && cd use-toggle
npm init -y
git init

Vamos construir um hook React simples chamado useToggle. Este exemplo demonstra a publicação de pacotes npm TypeScript com pontos de entrada adequados.

Configure o package.json para Publicação Moderna

Substitua seu package.json por uma versão adequadamente configurada:

{
  "name": "@yourusername/use-toggle",
  "version": "0.1.0",
  "description": "A simple React hook for boolean toggle state",
  "keywords": ["react", "hook", "toggle", "state"],
  "license": "MIT",
  "author": "Your Name",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/yourusername/use-toggle.git"
  },
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "engines": {
    "node": ">=18"
  },
  "peerDependencies": {
    "react": ">=18"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "react": "^18.0.0",
    "@types/react": "^18.0.0"
  },
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

Pontos-chave para esta configuração de pacote npm ESM-first:

• type: "module" declara ESM como padrão
• exports substitui o campo legado main—é assim que o Node moderno resolve pontos de entrada
• files controla o que é publicado (apenas dist/)
• engines especifica Node 18+, evitando problemas de compatibilidade legados

Configure a Compilação TypeScript

Crie tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Crie src/index.ts:

import { useState, useCallback } from 'react';

export function useToggle(initial = false): [boolean, () => void] {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue(v => !v), []);
  return [value, toggle];
}

Execute npm run build para compilar. Você obterá dist/index.js e dist/index.d.ts—JavaScript mais declarações de tipo, não TypeScript bruto.

Publicação Segura de Pacotes npm em 2025

Crie sua Conta npm com 2FA

1. Registre-se em npmjs.com
2. Habilite autenticação de dois fatores imediatamente (prefira WebAuthn/passkeys)
3. Todos os novos pacotes agora têm aplicação de 2FA habilitada por padrão
4. Com o novo modelo de login baseado em sessão, publicar qualquer pacote—novo ou existente—requer 2FA durante a sessão

Sua Primeira Publicação Manual

npm login agora cria um token de sessão de duas horas. Esses tokens:

• Não aparecem na interface do npm
• Expiram automaticamente após duas horas
• Não podem ser reutilizados em CI/CD
• Sempre aplicam 2FA antes de publicar

Ferramentas mais antigas que autenticam via endpoint CouchDB descontinuado também recebem tokens de sessão de duas horas durante o período de transição.

Para seu lançamento inicial:

npm login
npm publish --access public

A flag --access public é necessária para pacotes com escopo em contas gratuitas.

Verifique seu pacote em https://www.npmjs.com/package/@yourusername/use-toggle.

npm Trusted Publishing com CI

Tutoriais antigos dizem para criar um NPM_TOKEN e armazená-lo como secret do repositório. Esta abordagem agora está obsoleta: tokens clássicos foram permanentemente revogados, e tokens de CI de longa duração não são mais suportados.

A alternativa moderna é npm Trusted Publishing via GitHub Actions OIDC. O GitHub prova sua identidade ao npm, e o npm emite credenciais de curta duração automaticamente—nenhum token armazenado necessário.

Configure o Trusted Publishing

1. Em npmjs.com, vá para seu pacote → Settings → Publishing access
2. Adicione um novo “Trusted Publisher” com os detalhes do seu repositório GitHub

Crie o Workflow

Adicione .github/workflows/publish.yml:

name: Publish

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public

A flag --provenance adiciona atestação criptográfica vinculando seu pacote ao repositório de origem—um recurso de segurança da cadeia de suprimentos que o npm introduziu em 2023.

Se OIDC não puder ser usado (por exemplo, runners auto-hospedados), crie um token de acesso granular de curta duração usando:

npm token create

Tokens granulares podem optar por Bypass 2FA para publicação em CI e devem expirar em até 90 dias.

O Que Você Verá em Tutoriais Antigos

Evite estes padrões desatualizados:

• "main": "index.js" sem exports—use exports para resolução ESM adequada
• Direcionamento para Node 10/12/14—Node 18+ é suportado, mas novos pacotes devem direcionar versões LTS modernas (Node 20 ou 22)
• Pacotes apenas CommonJS—ESM é o padrão; publique ESM-first
• NPM_TOKEN permanente em cada workflow—tokens clássicos foram totalmente revogados; use Trusted Publishing sem token

Verifique Antes de Publicar

Sempre teste seu pacote localmente antes de publicar:

npm pack --dry-run

Isso mostra exatamente quais arquivos serão incluídos. Se você ver src/ ou node_modules/, seu campo files precisa de ajuste.

Conclusão

Para criar e publicar um pacote npm em 2025: use ESM com exports adequado, compile TypeScript para JavaScript com declarações, habilite 2FA e automatize releases com npm Trusted Publishing. Pule os padrões legados—eles causarão dores de cabeça para você e seus usuários.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.