Frontend Academy · Aula

Versionamento e publicação no npm

Utilizar versionamento semântico, automatizar a geração do registo de alterações com Changesets ou standard-version e publicar a biblioteca no npm ou num registo privado.

Aula 3 de 415 etapas

Versionamento e publicação no npm é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.

Por que publicar no npm?

Se o seu sistema de design for usado por mais de uma aplicação, publique-o como um pacote. Quem o utiliza instala com npm/yarn/pnpm, fixa versões e atualiza no próprio cronograma.

Versionamento semântico (SemVer)

As versões seguem MAJOR.MINOR.PATCH. MAJOR: alterações incompatíveis. MINOR: novas funcionalidades compatíveis com versões anteriores. PATCH: apenas correções de erros.

Quando incrementar a versão

Renomeou uma propriedade? MAJOR. Adicionou uma nova propriedade opcional? MINOR. Corrigiu um erro de CSS? PATCH. Lançamentos anteriores à versão 1.0 (0.x.y) podem incluir alterações incompatíveis em MINOR — mas seja cuidadoso.

package.json — o manifesto

Configure a aparência do seu pacote no npm.

{
  "name": "@yourorg/design-system",
  "version": "1.4.2",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js" },
    "./theme": "./dist/theme.js"
  },
  "files": ["dist", "README.md"],
  "peerDependencies": { "react": "^18.0.0" }
}

Saída da compilação

Distribua CommonJS, ESM e declarações de tipos. Ferramentas como tsup ou vite build --lib cuidam disso.

// tsup.config.ts
export default {
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom']
};

// package.json: "build": "tsup"

peerDependencies

Liste React/Vue etc. como peerDependencies para que quem utiliza o pacote use a própria versão. Marcá-los como dependências comuns inclui cada um duas vezes — o que quebra hooks e contexto.

Compatível com tree-shaking

Use exportações ESM e evite efeitos colaterais para que os empacotadores possam remover componentes não utilizados. Marque isso em package.json: "sideEffects": false (ou liste arquivos específicos, como CSS).

Publicando no npm

Faça login uma vez e depois publique.

npm login

# Bump version + publish:
npm version patch   # 1.4.2 -> 1.4.3
npm publish

# Or scoped public package:
npm publish --access public

Automatizando lançamentos com Changesets

Changesets é o conjunto de ferramentas moderno para publicação de bibliotecas em monorepos. Os pull requests incluem um arquivo de “changeset” descrevendo a alteração; a CI de lançamento incrementa as versões e publica.

npm install -D @changesets/cli
npx changeset init

# In each PR:
npx changeset
# pick package, type (major/minor/patch), describe change
# commits .changeset/<random>.md

# CI on main:
npx changeset version  # bumps versions in package.json + generates changelog
npx changeset publish  # publishes to npm

Registro de alterações automatizado

Changesets gera automaticamente um CHANGELOG.md para cada pacote a partir das descrições dos changesets — quem utiliza o pacote pode ler o que mudou em cada versão.

Tags de distribuição do npm

Use tags de distribuição para versões de pré-lançamento: npm publish --tag beta publica sem substituir a versão mais recente. Quem utiliza o pacote pode optar por ela com npm install @yourorg/design-system@beta.

Registros privados

Pacotes internos podem usar GitHub Packages, GitLab Package Registry ou o Verdaccio hospedado por você. Configure com .npmrc: @yourorg:registry=https://npm.pkg.github.com.

Descontinuando versões antigas

Marque uma versão como descontinuada para avisar quem fizer a instalação.

npm deprecate @yourorg/design-system@1.0.0 'Use 2.x for React 18 support'

Verificação rápida

Se você renomear uma propriedade em um componente exportado, que tipo de incremento de versão SemVer será necessário?

Responda na aula interativa

Recapitulação: versionamento e publicação

SemVer: MAJOR.MINOR.PATCH — alteração incompatível, funcionalidade e correção. Compile CJS + ESM + tipos (tsup, vite --lib). Use React/Vue como peerDependencies. sideEffects:false para tree-shaking. Publique com npm ou automatize com Changesets. O CHANGELOG é gerado automaticamente. Use tags de distribuição para versões beta. Registros privados para pacotes internos.

Grátis para começar

Aprenda HTML com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos: 41
Aulas: 163

Começar a aprender grátis Ver o curso completo

Perguntas Frequentes

A aula “Versionamento e publicação no npm” é grátis?

Sim — o texto completo de “Versionamento e publicação no npm” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.

O que vou aprender em “Versionamento e publicação no npm”?

Utilizar versionamento semântico, automatizar a geração do registo de alterações com Changesets ou standard-version e publicar a biblioteca no npm ou num registo privado. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Frontend Academy?

Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Versionamento e publicação no npm”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Frontend Academy?

Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Storybook: histórias, controlos e documentação
Tokens de design com Style Dictionary
Versionamento e publicação no npm
Consumo de um sistema de design

← Voltar para Frontend Academy