DEV Community

Cover image for Como Criar uma Biblioteca Angular e Publicar no NPM: Guia Completo
Ghabryel Henrique Ferreira e Almeida
Ghabryel Henrique Ferreira e Almeida

Posted on

Como Criar uma Biblioteca Angular e Publicar no NPM: Guia Completo

#webdev #programming #angular #npm

Você já se pegou copiando e colando os mesmos componentes entre projetos Angular? Ou desejou compartilhar aquele conjunto incrível de componentes com a comunidade? A solução está em criar sua própria biblioteca Angular e publicá-la no NPM.

Neste guia, vou te mostrar passo a passo como transformar seus componentes reutilizáveis em uma biblioteca profissional, pronta para ser instalada com um simples npm install.

O que é uma Library no Angular?

Uma biblioteca Angular é diferente de uma aplicação. Enquanto uma app é executada no navegador, uma library é compilada e empacotada para ser consumida por outras aplicações.

Pense assim: o Angular Material que você usa é uma library. O PrimeNG também. E agora você vai criar a sua!

Benefícios de criar uma library:

  • 🔄 Reutilização — Use os mesmos componentes em múltiplos projetos
  • 📦 Distribuição — Compartilhe facilmente via NPM (público ou privado)
  • 🔧 Manutenção centralizada — Corrija bugs uma vez, atualize em todos os projetos
  • 👥 Colaboração — Permita que outros devs contribuam com seu código

Passo 1: Criar o Workspace

O primeiro passo é criar um workspace Angular dedicado para sua biblioteca. A diferença aqui é que não vamos criar uma aplicação junto — apenas o workspace vazio.

# Criar workspace sem aplicação
ng new minha-biblioteca-workspace --no-create-application

# Entrar no diretório
cd minha-biblioteca-workspace
Enter fullscreen mode Exit fullscreen mode

O flag --no-create-application é importante porque evita a criação de uma aplicação padrão que não precisamos neste momento.

Agora, vamos gerar a biblioteca propriamente dita:

ng generate library minha-biblioteca
Enter fullscreen mode Exit fullscreen mode

Esse comando cria toda a estrutura necessária dentro de projects/minha-biblioteca/.

Passo 2: Entendendo a Estrutura de Arquivos

Após gerar a biblioteca, você terá a seguinte estrutura:

projects/
└── minha-biblioteca/
    ├── src/
    │   ├── lib/
    │   │   ├── minha-biblioteca.component.ts
    │   │   ├── minha-biblioteca.module.ts
    │   │   └── minha-biblioteca.service.ts
    │   └── public-api.ts  ⭐
    ├── ng-package.json
    └── package.json  ⭐
Enter fullscreen mode Exit fullscreen mode

Arquivos importantes:

public-api.ts — Este é o arquivo mais importante! Ele define o que será exportado da sua biblioteca. Tudo que não estiver listado aqui será código interno e inacessível para quem consumir sua lib.

// public-api.ts
export * from './lib/minha-biblioteca.service';
export * from './lib/minha-biblioteca.component';
export * from './lib/minha-biblioteca.module';
Enter fullscreen mode Exit fullscreen mode

package.json — Contém os metadados da sua biblioteca que serão publicados no NPM.

Passo 3: Desenvolvendo seus Componentes

Vamos criar um componente de exemplo. Dentro da biblioteca, você pode gerar componentes usando o Angular CLI:

ng generate component button --project=minha-biblioteca
Enter fullscreen mode Exit fullscreen mode

Aqui está um exemplo de componente de botão customizado:

// projects/minha-biblioteca/src/lib/button/button.component.ts
import { Component, Input, Output, EventEmitter } from '@angular/core';

@Component({
  selector: 'lib-button',
  template: `
    <button 
      [class]="'btn btn-' + variant"
      [disabled]="disabled"
      (click)="handleClick()">
      <ng-content></ng-content>
    </button>
  `,
  styles: [`
    .btn {
      padding: 12px 24px;
      border: none;
      border-radius: 8px;
      font-weight: 600;
      cursor: pointer;
      transition: all 0.2s ease;
    }
    .btn-primary {
      background: #dd0031;
      color: white;
    }
    .btn-primary:hover {
      background: #c3002f;
    }
    .btn-secondary {
      background: #424242;
      color: white;
    }
    .btn:disabled {
      opacity: 0.5;
      cursor: not-allowed;
    }
  `]
})
export class ButtonComponent {
  @Input() variant: 'primary' | 'secondary' = 'primary';
  @Input() disabled = false;
  @Output() clicked = new EventEmitter<void>();

  handleClick() {
    if (!this.disabled) {
      this.clicked.emit();
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Não esqueça de exportar no public-api.ts:

export * from './lib/button/button.component';
Enter fullscreen mode Exit fullscreen mode

Passo 4: Configurando o package.json

Antes de publicar, você precisa configurar corretamente o package.json da sua biblioteca (não o do workspace root!).

Abra projects/minha-biblioteca/package.json:

{
  "name": "@seu-usuario/minha-biblioteca",
  "version": "1.0.0",
  "description": "Uma biblioteca incrível de componentes Angular",
  "keywords": [
    "angular",
    "components",
    "ui",
    "library"
  ],
  "author": "Seu Nome <seu@email.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/seu-usuario/minha-biblioteca"
  },
  "bugs": {
    "url": "https://github.com/seu-usuario/minha-biblioteca/issues"
  },
  "homepage": "https://github.com/seu-usuario/minha-biblioteca#readme",
  "peerDependencies": {
    "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0",
    "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Sobre o escopo (@seu-usuario/)

Usar um escopo como @seu-usuario/ é uma boa prática porque:

  • Evita conflitos de nome com outros pacotes
  • Agrupa todas as suas bibliotecas sob um namespace
  • Fica mais profissional

Se você não tem uma organização no NPM, pode usar seu próprio username.

Sobre peerDependencies

O peerDependencies é crucial! Ele indica quais versões do Angular são compatíveis com sua biblioteca. Isso evita que o projeto consumidor instale versões duplicadas ou incompatíveis.

Passo 5: Compilando a Biblioteca

Agora vem a parte emocionante — compilar sua biblioteca para produção:

ng build minha-biblioteca
Enter fullscreen mode Exit fullscreen mode

Você verá uma saída similar a esta:

Building Angular Package

------------------------------------------------------------------------------
Building entry point '@seu-usuario/minha-biblioteca'
------------------------------------------------------------------------------
✔ Compiling with Angular sources in Ivy partial compilation mode.
✔ Generating FESM bundles
✔ Copying assets
✔ Writing package manifest
✔ Built @seu-usuario/minha-biblioteca

------------------------------------------------------------------------------
Built Angular Package
 - from: /projects/minha-biblioteca
 - to:   /dist/minha-biblioteca
------------------------------------------------------------------------------
Enter fullscreen mode Exit fullscreen mode

Os arquivos compilados ficam em dist/minha-biblioteca/. Esta pasta contém tudo que será publicado no NPM.

Passo 6: Testando Localmente (Opcional mas Recomendado!)

Antes de publicar, é uma boa ideia testar sua biblioteca localmente. Use o npm link:

# Na pasta da biblioteca compilada
cd dist/minha-biblioteca
npm link

# Em outro projeto Angular onde quer testar
cd /caminho/para/outro-projeto
npm link @seu-usuario/minha-biblioteca
Enter fullscreen mode Exit fullscreen mode

Agora você pode importar e usar sua biblioteca no projeto de teste:

import { MinhaBibliotecaModule } from '@seu-usuario/minha-biblioteca';

@NgModule({
  imports: [MinhaBibliotecaModule]
})
export class AppModule { }
Enter fullscreen mode Exit fullscreen mode

Passo 7: Publicando no NPM 🚀

Chegou a hora! Primeiro, faça login no NPM (crie uma conta em npmjs.com se ainda não tiver):

npm login
Enter fullscreen mode Exit fullscreen mode

Navegue até a pasta dist e publique:

cd dist/minha-biblioteca
npm publish --access public
Enter fullscreen mode Exit fullscreen mode

O flag --access public é obrigatório para pacotes com escopo (@seu-usuario/) que você quer tornar públicos. Sem ele, o NPM assume que é um pacote privado (que requer plano pago).

🎉 Parabéns! Sua biblioteca está no mundo!

Agora qualquer pessoa pode instalar com:

npm install @seu-usuario/minha-biblioteca
Enter fullscreen mode Exit fullscreen mode

Atualizando sua Biblioteca

Quando fizer melhorias ou correções, você precisa atualizar a versão antes de republicar:

# Para correções de bugs (1.0.0 -> 1.0.1)
npm version patch

# Para novas features retrocompatíveis (1.0.0 -> 1.1.0)
npm version minor

# Para breaking changes (1.0.0 -> 2.0.0)
npm version major
Enter fullscreen mode Exit fullscreen mode

Depois, compile e publique novamente:

ng build minha-biblioteca
cd dist/minha-biblioteca
npm publish
Enter fullscreen mode Exit fullscreen mode

Dicas Avançadas

1. Adicione uma aplicação de demonstração

Crie uma app dentro do mesmo workspace para demonstrar sua biblioteca:

ng generate application demo
Enter fullscreen mode Exit fullscreen mode

2. Configure o Storybook

O Storybook é excelente para documentar componentes visualmente:

npx storybook@latest init
Enter fullscreen mode Exit fullscreen mode

3. Adicione testes

Não esqueça de testar seus componentes:

ng test minha-biblioteca
Enter fullscreen mode Exit fullscreen mode

4. Use Standalone Components (Angular 14+)

Se estiver usando Angular 14+, considere criar componentes standalone para facilitar o tree-shaking:

@Component({
  selector: 'lib-button',
  standalone: true,
  imports: [CommonModule],
  template: `...`
})
export class ButtonComponent { }
Enter fullscreen mode Exit fullscreen mode

5. Crie um README atraente

Um bom README no repositório faz toda a diferença. Inclua:

  • Instalação
  • Como usar
  • Exemplos de código
  • API dos componentes
  • Screenshots/GIFs

Conclusão

Criar e publicar uma biblioteca Angular pode parecer intimidador no início, mas como vimos, o processo é bem direto:

  1. Criar o workspace e a library
  2. Desenvolver seus componentes
  3. Configurar o package.json
  4. Compilar para produção
  5. Publicar no NPM

Agora você tem o poder de compartilhar seu código com milhões de desenvolvedores ao redor do mundo. Que tal começar com aquele conjunto de componentes que você sempre quis padronizar?

Recursos Úteis

Gostou do artigo? Deixe um like e compartilhe com outros devs Angular! Se tiver dúvidas, comenta aí que eu respondo. 🚀

Tags: #angular #npm #javascript #typescript #webdev #frontend #library #opensource #tutorial

Top comments (0)