Parte 3: Criando Bibliotecas Angular

Utilizando Sua Própria Biblioteca em Aplicações: Desfrutando dos Frutos do seu Trabalho

Criar bibliotecas Angular é uma excelente maneira de compartilhar funcionalidades reutilizáveis entre diferentes aplicações. No entanto, quando se trata de usar essas bibliotecas, especialmente durante o desenvolvimento, você pode preferir integrá-las diretamente em seu workspace sem precisar publicá-las no npm. Neste artigo, veremos como usar sua própria biblioteca Angular em aplicações dentro do mesmo workspace.

Construindo a Biblioteca: Preparando a Nave para o Lançamento

Antes de utilizar sua biblioteca em uma aplicação, você precisa construí-la para garantir que o código esteja compilado e otimizado.

Construa a Biblioteca

O primeiro passo é construir a biblioteca usando o comando ng build. Isso criará a versão de distribuição da biblioteca na pasta dist do seu workspace.

ng build my-lib

Nota: O nome my-lib deve corresponder ao nome do projeto da biblioteca definido em seu arquivo angular.json.

Importe a Biblioteca na Aplicação

Com a biblioteca construída, você pode importá-la na sua aplicação Angular. No arquivo do módulo da aplicação, adicione o import para os módulos ou componentes que você deseja utilizar.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { MyLibModule } from 'my-lib'; // Importa o módulo da biblioteca

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    MyLibModule // Adiciona o módulo da biblioteca aos imports
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Verifique se os Caminhos de Importação Estão Corretos

Certifique-se de que os caminhos de importação estão corretos e que estão se referindo ao nome da biblioteca conforme definido no package.json da biblioteca. A importação deve ser feita pelo nome do pacote e não por caminhos relativos.

import { MyService } from 'my-lib'; // Certifique-se de usar o nome do pacote

Atualize a Aplicação Quando a Biblioteca Mudar

Se você fizer alterações na biblioteca, precisará reconstruí-la para que as mudanças estejam disponíveis na aplicação. Após reconstruir a biblioteca, a aplicação deve ser reiniciada para refletir as alterações.

ng build my-lib
ng serve

1. Dica: Utilize ferramentas de automação, como scripts npm, para facilitar esse processo, especialmente se você estiver em um ambiente de desenvolvimento ativo.

Boas Práticas para Desenvolvimento

• Uso de Monorepo: Ao trabalhar com múltiplas bibliotecas e aplicações, considere usar uma abordagem monorepo, onde todos os projetos residem em um único repositório. Isso facilita a gestão de dependências e o compartilhamento de código.
• Testes Unitários: Certifique-se de que tanto a biblioteca quanto a aplicação possuem testes unitários adequados para garantir que as integrações funcionem conforme esperado.
• Documentação: Mantenha uma documentação clara sobre como usar a biblioteca, incluindo exemplos de uso e quaisquer requisitos especiais de configuração.

Construindo e Reconstruindo sua Biblioteca: Mantendo a Nave em Perfeito Estado de Voo

A medida que você desenvolve sua biblioteca Angular, é fundamental garantir que as alterações feitas sejam refletidas corretamente nas aplicações que a utilizam. O processo de construção e reconstrução da biblioteca desempenha um papel crucial nessa sincronização, permitindo que você teste e refine suas funcionalidades em tempo real.

A biblioteca, uma vez construída, pode ser usada em múltiplas aplicações sem a necessidade de ser publicada no npm, desde que as etapas de construção sejam seguidas corretamente.

A Importância da Construção: O Abastecimento da Nave

O processo de construção transforma o código TypeScript da biblioteca em JavaScript, tornando-o utilizável pelas aplicações Angular. Sem esta etapa, os imports da biblioteca aparecerão como ausentes no editor, pois a aplicação não conseguirá encontrar os arquivos necessários no disco.

Nota Importante: Quando você importa algo de uma biblioteca em uma aplicação Angular, o Angular busca um mapeamento entre o nome da biblioteca e um local no disco. Este mapeamento é geralmente encontrado na pasta node_modules quando a biblioteca é instalada via npm. No caso de bibliotecas desenvolvidas localmente, o mapeamento é feito através das configurações de caminho no arquivo tsconfig.json.

Gerando e Configurando Bibliotecas com o Angular CLI

Ao gerar uma biblioteca com o Angular CLI, o caminho da biblioteca é automaticamente adicionado ao arquivo tsconfig.json. Isso é crucial para que o sistema de construção saiba onde encontrar a biblioteca no disco.

// Exemplo de configuração no tsconfig.json
"compilerOptions": {
  "paths": {
    "my-lib": ["dist/my-lib"]
  }
}

Este mapeamento garante que o Angular CLI possa encontrar a biblioteca durante o processo de construção da aplicação.

Reconstruindo a Biblioteca

Alterações na biblioteca exigem uma reconstrução para que as mudanças sejam refletidas nas aplicações que dependem dela. No entanto, o processo de construção pode ser demorado, especialmente em grandes bibliotecas. Para melhorar a experiência de desenvolvimento, você pode usar construções incrementais.

Construções Incrementais

Construções incrementais permitem que a biblioteca seja reconstruída automaticamente sempre que um arquivo é alterado. Isso economiza tempo e simplifica o fluxo de trabalho, especialmente durante o desenvolvimento ativo.

Para ativar construções incrementais, use o comando de construção com a flag --watch:

ng build my-lib --watch

Diferenças Entre os Sistemas de Construção

É importante entender que o Angular CLI utiliza diferentes sistemas de construção para aplicações e bibliotecas:

• Aplicações: Usam o sistema de construção baseado em webpack (via @angular-devkit/build-angular), incluído em todos os novos projetos Angular CLI.
• Bibliotecas: Usam o sistema de construção baseado em ng-packagr, que é adicionado às dependências somente quando uma biblioteca é criada com ng generate library.

Esses sistemas de construção suportam funcionalidades diferentes e, mesmo onde suportam as mesmas funcionalidades, podem produzir resultados distintos em termos de código JavaScript gerado. Isso significa que uma aplicação que depende de uma biblioteca deve sempre usar mapeamentos de caminho TypeScript que apontem para a biblioteca construída, e não para os arquivos de origem .ts.

Práticas Recomendadas

• Sempre Construa Antes de Usar: Garanta que a biblioteca esteja construída antes de ser usada em uma aplicação.
• Use Caminhos Mapeados: Configure corretamente os caminhos no tsconfig.json para garantir que a aplicação encontre a biblioteca construída.
• Aproveite as Construções Incrementais: Use a flag --watch para facilitar o desenvolvimento e reduzir o tempo de iteração.

Mantendo sua Biblioteca Sempre Pronta para o Lançamento

Com o Angular CLI e a funcionalidade de builds incrementais, você pode manter sua biblioteca Angular sempre atualizada e pronta para ser utilizada em suas aplicações. Ao entender as diferenças entre os sistemas de build de aplicações e bibliotecas, você garante a compatibilidade e o bom funcionamento do seu código, permitindo que sua nave espacial Angular explore o universo da web com confiança e eficiência.

Publicando Bibliotecas: Lançando sua Criação ao Universo Angular

Após construir e refinar sua biblioteca Angular, é hora de compartilhá-la com o mundo, permitindo que outros desenvolvedores se beneficiem de suas funcionalidades e recursos. A publicação da sua biblioteca como um pacote npm é o passo final dessa jornada, abrindo as portas para que sua criação seja descoberta e utilizada por toda a comunidade Angular.

Formatos de Distribuição

Existem dois formatos principais de distribuição para bibliotecas Angular:

1. Partial-Ivy (Recomendado)
   • Detalhes: Este formato contém código portável que pode ser consumido por aplicações Ivy construídas com qualquer versão do Angular a partir da v12.
   • Vantagens: É estável entre as versões patch do Angular, o que significa que o código gerado é menos propenso a quebrar quando o Angular é atualizado.
   • Uso Recomendado: Deve ser usado ao publicar bibliotecas no npm, pois oferece maior compatibilidade e estabilidade.
2. Full-Ivy
   • Detalhes: Contém instruções privadas do Angular Ivy, que não são garantidas para funcionar em diferentes versões do Angular.
   • Desvantagens: Este formato requer que a biblioteca e a aplicação sejam construídas com a mesma versão exata do Angular. As instruções Ivy geradas não fazem parte da API pública do Angular e podem mudar entre versões.
   • Uso Específico: Útil em ambientes onde todo o código da biblioteca e da aplicação é construído diretamente a partir do código-fonte, sem a necessidade de reutilização em ambientes diferentes.

Por Que Usar o Formato Partial-Ivy?

Ao publicar sua biblioteca no npm, é altamente recomendável usar o formato Partial-Ivy. Este formato é projetado para ser estável e compatível entre diferentes versões do Angular, facilitando a integração da biblioteca em diversos projetos que podem estar em diferentes fases de atualização do Angular.

Vantagens do Partial-Ivy

• Portabilidade: Código portável que pode ser consumido por diferentes versões do Angular.
• Estabilidade: Menor risco de quebra entre atualizações patch, pois o formato é projetado para ser consistente.
• Compatibilidade: Permite que sua biblioteca seja usada por uma ampla gama de aplicações, sem a necessidade de especificar uma versão específica do Angular.

Considerações ao Publicar no npm

• Evite Full-Ivy no npm: O uso de full-Ivy em bibliotecas publicadas no npm é desencorajado devido às possíveis incompatibilidades causadas por alterações nas instruções privadas do Ivy entre versões.
• Estratégia de Versão: Ao usar partial-Ivy, é mais fácil manter a compatibilidade sem precisar atualizar constantemente as dependências para coincidir com a última versão do Angular.
• Documentação e Testes: Garanta que sua biblioteca venha acompanhada de documentação clara e de testes que ajudem a validar a funcionalidade em diferentes versões do Angular.

Compartilhando sua Criação com o Mundo

A publicação da sua biblioteca no npm é um passo emocionante, que permite que você compartilhe sua criação com outros desenvolvedores e contribua para o crescimento do ecossistema Angular. Ao seguir as melhores práticas e escolher o formato de distribuição adequado, você garante que sua biblioteca seja acessível, compatível e pronta para ser utilizada em diversos projetos.

Garantindo a Compatibilidade de Versões da sua Biblioteca: Um Mapa Estelar para Evitar Colisões

Ao desenvolver bibliotecas Angular, é essencial garantir que as versões usadas para construir a aplicação e suas bibliotecas dependentes sejam compatíveis. A versão do Angular usada para construir uma aplicação deve sempre ser a mesma ou mais recente que a versão do Angular usada para construir qualquer uma de suas bibliotecas dependentes. Isso assegura que as funcionalidades mais recentes e correções de bugs estejam disponíveis e que não haja conflitos de versão que possam causar problemas durante o tempo de execução.

Diretrizes para Compatibilidade de Versão

1. Consistência de Versão
   • Regra Geral: A aplicação deve usar a mesma versão do Angular ou uma versão posterior à usada pelas bibliotecas de que depende.
   • Exemplo: Se uma biblioteca for construída usando o Angular versão 13, a aplicação que depende dessa biblioteca deve usar o Angular versão 13 ou posterior. Usar uma versão anterior para a aplicação não é suportado pelo Angular.
2. Compilação com Código Partial-Ivy
   • Recomendação: Ao publicar sua biblioteca no npm, compile-a com código Partial-Ivy. Para isso, configure "compilationMode": "partial" em tsconfig.prod.json.
   • Vantagem: O formato Partial-Ivy é estável entre diferentes versões do Angular, o que o torna seguro para publicação no npm. O código neste formato é processado durante a construção da aplicação usando a mesma versão do compilador Angular, garantindo que a aplicação e todas as suas bibliotecas utilizem uma única versão do Angular.
   • Estabilidade: Ao usar o formato Partial-Ivy, você garante que sua biblioteca será compatível com versões futuras do Angular, sem exigir atualizações constantes para coincidir com as versões mais recentes do framework.
3. Evitar Compilação com Código Full-Ivy
   • Motivo: Compilar bibliotecas com código Full-Ivy para publicação no npm não é recomendado porque as instruções Ivy geradas não fazem parte da API pública do Angular e podem mudar entre versões patch.
   • Implicações: Usar o formato Full-Ivy pode resultar em problemas de compatibilidade quando diferentes versões do Angular são usadas, pois as instruções internas podem não ser compatíveis entre diferentes versões do framework.
4. Publicação no npm
   • Requisitos: Se você nunca publicou um pacote no npm antes, deve criar uma conta de usuário. Consulte mais detalhes em Publicação de Pacotes npm.
   • Processo: Após configurar sua biblioteca corretamente e verificar a compatibilidade de versão, use comandos como ng build my-lib seguido de npm publish para compilar e publicar sua biblioteca no npm.

Uma Viagem Segura e Compatível

Ao garantir a compatibilidade de versões da sua biblioteca, você oferece aos seus usuários uma experiência de desenvolvimento mais tranquila e livre de problemas. Com o Angular CLI e as melhores práticas de publicação, sua biblioteca estará pronta para ser utilizada em diversos projetos Angular, impulsionando a colaboração e a inovação no ecossistema.

Consumindo Código Partial-Ivy Fora do Angular CLI: A Ponte para Outros Mundos

Ao trabalhar com bibliotecas Angular que utilizam o formato Partial-Ivy, é importante saber como consumir esse código em aplicações que não utilizam o Angular CLI. Este artigo explora como integrar o código Partial-Ivy em ambientes personalizados e detalha as etapas necessárias para configurar o processo de construção para garantir que as bibliotecas sejam corretamente compiladas e incorporadas nas aplicações.

Introdução ao Consumo de Bibliotecas Partial-Ivy

Quando uma aplicação instala bibliotecas Angular do npm em seu diretório node_modules, o código dessas bibliotecas não está completamente compilado. Para concluir a compilação, é necessário usar o Angular linker. O linker é uma ferramenta que transforma o código Partial-Ivy em uma forma totalmente compilada que pode ser executada em navegadores.

Uso do Angular Linker em Aplicações que Não Usam Angular CLI

Para aplicações que não utilizam o Angular CLI, o linker está disponível como um plugin Babel. Este plugin é importado do pacote @angular/compiler-cli/linker/babel. Ele é responsável por processar o código das bibliotecas Angular para que possa ser incorporado na aplicação final.

Integração do Plugin Babel com Webpack

O exemplo a seguir demonstra como integrar o plugin linker do Angular em uma construção personalizada usando Webpack. Isso é feito registrando o linker como um plugin Babel utilizando o babel-loader.

Exemplo de Configuração do Webpack

// webpack.config.mjs

import linkerPlugin from '@angular/compiler-cli/linker/babel';

export default {
  module: {
    rules: [
      {
        test: /\.m?js$/,
        use: {
          loader: 'babel-loader',
          options: {
            plugins: [linkerPlugin],
            compact: false,
            cacheDirectory: true,
          }
        }
      }
    ]
  }
}

Explicação da Configuração

• test: /\.m?js$/: Esta regra aplica o loader Babel a todos os arquivos JavaScript e módulos ES6.
• loader: 'babel-loader': Utiliza o babel-loader para processar os arquivos JavaScript.
• plugins: [linkerPlugin]: Registra o plugin linker do Angular, que transforma o código Partial-Ivy em código executável.
• compact: false: Define se o Babel deve compactar o código de saída. Definido como false para facilitar a depuração.
• cacheDirectory: true: Habilita o cache para melhorar o desempenho das compilações subsequentes, garantindo que as bibliotecas sejam processadas pelo linker apenas uma vez, independentemente de outras operações do npm.

Importância do Plugin Linker

O plugin Babel do Angular linker suporta cache de compilação, o que significa que as bibliotecas só precisam ser processadas pelo linker uma vez. Isso é vantajoso, pois reduz o tempo de compilação e otimiza o processo de construção, especialmente em projetos grandes que utilizam várias bibliotecas Angular.

Integração com o Angular CLI

É importante destacar que o Angular CLI integra o plugin linker automaticamente. Portanto, se os consumidores da sua biblioteca estiverem usando o Angular CLI, eles podem instalar bibliotecas nativas do Ivy do npm sem necessidade de configuração adicional.

Conclusão

O uso do Angular linker é crucial para aplicações que não utilizam o Angular CLI, garantindo que o código Partial-Ivy seja corretamente transformado em código executável. Este guia fornece uma visão geral das etapas necessárias para integrar o linker em uma configuração personalizada de Webpack, permitindo que desenvolvedores consumam bibliotecas Angular de maneira eficaz em diferentes ambientes de desenvolvimento. Ao adotar essas práticas, as bibliotecas podem ser usadas de forma consistente em diversos projetos, promovendo a reutilização de código e a eficiência do desenvolvimento.

Criação e Gerenciamento de Bibliotecas Angular

Nesta série de artigos, exploramos a criação e o gerenciamento de bibliotecas Angular, desde a concepção inicial até a publicação e integração em aplicações. Vamos revisar os principais tópicos abordados:

1. Introdução e Criação de Bibliotecas

Ao criar uma biblioteca Angular, começamos configurando o ambiente de desenvolvimento e gerando uma estrutura básica com o Angular CLI. As bibliotecas Angular oferecem soluções reutilizáveis que podem ser distribuídas como pacotes npm, permitindo que desenvolvedores compartilhem componentes, serviços e outras funcionalidades em diferentes projetos.

2. Refatorando Partes de uma Aplicação em uma Biblioteca

Refatorar funcionalidades de uma aplicação para uma biblioteca envolve separar o código reutilizável do código específico da aplicação. Isso requer a eliminação de dependências específicas da aplicação e a criação de componentes e serviços que sejam independentes e reutilizáveis, com interfaces claras para comunicação.

3. Integração com o Angular CLI Usando Schematics

Integrar bibliotecas com o Angular CLI por meio de schematics é uma prática poderosa. Os schematics permitem automatizar a geração de código e a configuração de funcionalidades nas aplicações que consomem a biblioteca. Isso inclui adicionar comandos como ng add para instalação, ng generate para criação de artefatos, e ng update para atualizações de dependências.

4. Publicação de Bibliotecas

Publicar uma biblioteca envolve empacotar o código para distribuição no npm. O Angular CLI usa o ng-packagr para criar pacotes compatíveis com npm, e a publicação é feita através do comando npm publish. É importante seguir as diretrizes de versão e compatibilidade para garantir que a biblioteca seja consumível por diversas versões do Angular.

5. Gerenciamento de Ativos em uma Biblioteca

Além do código, bibliotecas podem incluir ativos adicionais, como arquivos de temas, mixins Sass, e documentação. Gerenciar esses ativos corretamente garante que eles sejam distribuídos juntamente com a biblioteca e acessíveis aos consumidores.

6. Dependências de Par

Bibliotecas Angular devem listar dependências do Angular como dependências de par (peer dependencies) para garantir que todas as instâncias de Angular no projeto sejam consistentes. Isso evita conflitos de versão e problemas de compatibilidade.

7. Uso de Bibliotecas em Aplicações

Utilizar uma biblioteca em uma aplicação no mesmo workspace requer a construção prévia da biblioteca. Aplicações importam o código da biblioteca por nome, conforme definido nas configurações de caminho do TypeScript (tsconfig).

8. Construção e Reconstrução da Biblioteca

Construir e reconstruir a biblioteca é essencial durante o desenvolvimento para refletir mudanças no código. O uso de builds incrementais e o comando ng build --watch melhoram a experiência de desenvolvimento ao reduzir o tempo de compilação.

9. Publicação de Bibliotecas

Ao publicar bibliotecas, o formato recomendado é o Partial-Ivy, que é estável entre diferentes versões do Angular. Evitar o uso de código full-Ivy em bibliotecas publicadas é importante para garantir compatibilidade entre versões.

10. Garantindo Compatibilidade de Versão da Biblioteca

A versão do Angular usada para construir uma aplicação deve ser igual ou superior à versão usada para construir suas bibliotecas dependentes. Compilar bibliotecas com o formato Partial-Ivy assegura que o código seja estável entre versões e seguro para publicação no npm.

11. Consumo de Código Partial-Ivy Fora do Angular CLI

Para aplicações que não utilizam o Angular CLI, o consumo de código Partial-Ivy requer o uso do Angular linker, disponível como um plugin Babel. Integrar o plugin linker em sistemas de build personalizados, como Webpack, é crucial para finalizar a compilação e tornar o código executável.

Considerações Finais

Criar bibliotecas Angular é um investimento que oferece benefícios significativos em termos de reutilização de código e consistência entre projetos. Esta série de artigos abordou as etapas necessárias para criar, gerenciar e publicar bibliotecas Angular de forma eficaz. Com a compreensão desses conceitos, desenvolvedores podem expandir a funcionalidade de suas aplicações e compartilhar soluções com a comunidade Angular de maneira eficiente.