Parte 2: Criando Bibliotecas Angular

Integrando com o Angular CLI: Schematics como a Ponte para sua Biblioteca

Uma biblioteca Angular geralmente inclui código reutilizável que define componentes, serviços e outros artefatos do Angular, como pipes e diretivas, que podem ser importados em um projeto. Além de ser empacotada como um pacote npm para publicação e compartilhamento, uma biblioteca pode incluir schematics que fornecem instruções para gerar ou transformar código diretamente no seu projeto.

Os schematics funcionam de maneira semelhante ao CLI do Angular quando você cria um novo componente genérico com o comando ng generate component. Um schematic empacotado com uma biblioteca pode, por exemplo, fornecer ao Angular CLI as informações necessárias para gerar um componente que configura e utiliza um recurso específico ou um conjunto de recursos definidos nessa biblioteca. Um exemplo disso é o schematic de navegação do Angular Material, que configura o BreakpointObserver do CDK e o utiliza com os componentes MatSideNav e MatToolbar do Material.

Criando e incluindo schematics

Ao desenvolver uma biblioteca, considere incluir os seguintes tipos de schematics:

Schematic de atualização: Inclua um schematic de atualização para que o comando ng update possa atualizar as dependências da sua biblioteca e fornecer migrações para mudanças incompatíveis em novas versões. Isso facilita a manutenção e atualização da sua biblioteca ao longo do tempo, garantindo que os desenvolvedores possam migrar facilmente para novas versões sem quebrar o código existente.

Schematic de instalação: Inclua um schematic de instalação para que o comando ng add possa adicionar sua biblioteca a um projeto. Este schematic pode configurar automaticamente a aplicação para utilizar sua biblioteca corretamente, como adicionar dependências necessárias ou importar módulos.

Schematics de geração: Inclua schematics de geração na sua biblioteca para que o comando ng generate possa criar artefatos definidos (como componentes, serviços e testes) em um projeto. Isso permite que desenvolvedores utilizem facilmente sua biblioteca para criar componentes predefinidos e configurá-los conforme necessário.

Exemplo: O Schematic de Navegação do Angular Material

Um exemplo prático do poder dos Schematics é o navigation schematic do Angular Material. Esse Schematic configura o BreakpointObserver do CDK (Component Dev Kit) e o utiliza com os componentes MatSideNav e MatToolbar do Material, gerando um sistema de navegação responsivo e completo em poucos passos.

Decidindo o que incluir em sua biblioteca

O que você inclui na sua biblioteca depende das suas necessidades específicas. Por exemplo, você poderia definir um schematic para criar um dropdown que já vem preenchido com dados predefinidos para mostrar como adicioná-lo a uma aplicação. Se você deseja que o dropdown contenha valores diferentes passados a cada vez, sua biblioteca poderia definir um schematic para criá-lo com uma configuração específica. Assim, os desenvolvedores poderiam usar o comando ng generate para configurar uma instância para sua própria aplicação.

Considere a seguinte situação: suponha que você deseja ler um arquivo de configuração e, em seguida, gerar um formulário com base nessa configuração. Se esse formulário precisar de personalizações adicionais por parte do desenvolvedor que está usando sua biblioteca, pode ser mais adequado implementá-lo como um schematic. No entanto, se o formulário for sempre o mesmo e não precisar de muitas personalizações pelos desenvolvedores, você poderia criar um componente dinâmico que recebe a configuração e gera o formulário.

Quando usar schematics

Em geral, quanto mais complexa for a personalização necessária, mais útil será a abordagem com schematics. Schematics permitem um alto nível de customização e flexibilidade para os desenvolvedores que utilizam sua biblioteca, facilitando a configuração de componentes e recursos de acordo com as necessidades específicas de cada projeto.

Compartilhe sua Tecnologia com o Universo Angular

Ao integrar sua biblioteca com o Angular CLI através de Schematics, você está abrindo as portas para um público mais amplo, oferecendo uma experiência de usuário superior e impulsionando a adoção da sua criação. Com o poder da automação e da personalização, os Schematics transformam sua biblioteca em uma ferramenta indispensável para os exploradores do universo Angular.

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

Após criar e testar 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.

Utilizando o ng-packagr

O Angular CLI utiliza uma ferramenta chamada ng-packagr para criar pacotes a partir do código compilado que podem ser publicados no npm. Essa ferramenta cuida da maior parte do trabalho pesado de empacotar sua biblioteca corretamente, assegurando que ela esteja no formato apropriado para distribuição.

Para informações detalhadas sobre os formatos de distribuição suportados pelo ng-packagr e orientações sobre como escolher o formato certo para sua biblioteca, consulte a documentação sobre Construindo bibliotecas com Ivy.

Compilando sua biblioteca para produção

É essencial compilar suas bibliotecas para distribuição usando a configuração de produção. Isso garante que a saída gerada use as otimizações apropriadas e o formato correto para o npm. Compilar em modo de produção aplica diversas otimizações, como minificação de código e eliminação de código morto, que ajudam a reduzir o tamanho do pacote e melhorar o desempenho.

Para compilar sua biblioteca com o Angular CLI, execute o seguinte comando no terminal:

ng build my-lib --configuration production

Publicando no npm

Após compilar sua biblioteca, você estará pronto para publicá-la no npm. Primeiro, navegue até o diretório dist onde a biblioteca compilada foi gerada:

cd dist/my-lib

Antes de publicar, é uma boa prática garantir que o package.json esteja corretamente configurado, especialmente os campos name, version, e main, que são críticos para o funcionamento da biblioteca quando publicada.

Certifique-se de que o nome da biblioteca no package.json seja único no npm, para evitar conflitos com pacotes já existentes. Se você planeja publicar a biblioteca em um registro privado de npm, como um registry corporativo, pode ajustar o campo publishConfig no package.json para apontar para o registro correto.

Em seguida, publique sua biblioteca com o comando npm publish:

npm publish

Considerações

Publicar uma biblioteca no npm é um passo significativo que requer atenção para detalhes como compatibilidade de versão, conformidade com padrões de código e documentação. Aqui estão algumas dicas adicionais a considerar:

• Versionamento Semântico: Use versionamento semântico (semver) para controlar as versões da sua biblioteca. Isso ajuda usuários da sua biblioteca a entenderem rapidamente a natureza das mudanças entre as versões (correções de bugs, novas funcionalidades ou mudanças incompatíveis).
• Documentação: Inclua documentação clara e detalhada no pacote, geralmente em um arquivo README.md. Isso deve incluir instruções sobre como instalar, configurar e usar a biblioteca, além de exemplos de uso.
• Testes e Qualidade de Código: Certifique-se de que sua biblioteca está bem testada e que o código atende aos padrões de qualidade antes da publicação. Isso pode incluir execução de testes unitários, verificação de cobertura de testes e uso de ferramentas de lint para assegurar a consistência do código.
• Dependências: Revise as dependências e dependências de pares (peer dependencies) no package.json para garantir que estão corretamente listadas e versionadas.

Publicar uma biblioteca no npm não apenas torna seu trabalho disponível para outros desenvolvedores, mas também amplia sua contribuição para a comunidade Angular, permitindo que outros se beneficiem da sua experiência e soluções. Nos próximos artigos, exploraremos como gerenciar ativos dentro de uma biblioteca, lidar com dependências e usar sua própria biblioteca em aplicações Angular.

Gerenciando Recursos em uma Biblioteca: Embarcando Tesouros Extras em sua Nave Espacial

Além do código-fonte em si, sua biblioteca Angular pode conter recursos adicionais, como arquivos de temas, mixins Sass ou documentação (como um changelog). Esses recursos extras enriquecem a experiência do usuário, oferecendo opções de personalização, ferramentas de estilo e informações úteis sobre a biblioteca.

Tipos de Ativos

Os ativos que você pode querer incluir em sua biblioteca podem variar dependendo da funcionalidade que ela fornece. Aqui estão alguns exemplos comuns:

• Arquivos de Temas: Arquivos CSS ou SCSS que definem estilos e temas que podem ser aplicados aos componentes fornecidos pela biblioteca.
• Mixins de Sass: Funções de Sass reutilizáveis que ajudam a personalizar os estilos dos componentes.
• Documentação: Arquivos como README.md ou CHANGELOG.md que fornecem informações essenciais sobre a biblioteca, incluindo instruções de uso e histórico de alterações.

Incluindo Ativos no Pacote Distribuível

Para incluir ativos adicionais no pacote distribuível da sua biblioteca, você pode seguir estas diretrizes:

1. Arquivos Sass e CSS Pré-Compilados:Quando sua biblioteca inclui mixins de Sass ou CSS pré-compilado, é necessário adicionar esses arquivos manualmente às exportações condicionais no package.json do ponto de entrada principal da sua biblioteca. Isso garante que esses arquivos estejam acessíveis quando a biblioteca é instalada e usada em um projeto Angular.Aqui está um exemplo de como adicionar essas exportações:

"exports": {
  ".": {
    "sass": "./_index.scss",
  },
  "./theming": {
    "sass": "./_theming.scss"
  },
  "./prebuilt-themes/indigo-pink.css": {
    "style": "./prebuilt-themes/indigo-pink.css"
  }
}

Este exemplo mostra um trecho das exportações do @angular/material. Ele inclui um arquivo principal de Sass (_index.scss), um arquivo de temas (_theming.scss), e um arquivo CSS pré-compilado (indigo-pink.css) como parte das exportações.

2. Copiando Ativos Durante o Processo de Build:

Você pode configurar seu processo de build para copiar automaticamente arquivos de ativos para o diretório de distribuição. Isso pode ser feito configurando scripts de build que usem ferramentas como o copyfiles para mover arquivos para o diretório dist antes da publicação.

3. Incorporando Ativos em Estilos de Componentes:

Se sua biblioteca inclui estilos específicos para componentes, considere incorporar esses estilos diretamente nos arquivos de estilos dos componentes. Isso pode ser feito usando o styles ou styleUrls no decorador @Component, permitindo que estilos específicos sejam incluídos automaticamente quando o componente é usado.

Uma Biblioteca Rica em Recursos

Ao gerenciar seus recursos com sabedoria e configurar as exportações corretamente, você transforma sua biblioteca Angular em um tesouro repleto de funcionalidades e ferramentas úteis para os desenvolvedores. Com o Angular CLI como seu guia, você está pronto para compartilhar sua criação com o mundo e impulsionar a inovação no ecossistema Angular.

Dependências Peer: Garantindo a Harmonia na Frota Estelar Angular

Quando você desenvolve uma biblioteca Angular, é essencial gerenciar corretamente as dependências de par (peer dependencies) para garantir que sua biblioteca funcione sem problemas em conjunto com outras bibliotecas Angular e dentro das aplicações que a utilizam. A gestão adequada das dependências de par é crítica para evitar conflitos de versão e garantir a compatibilidade do seu código.

O que são Dependências Peer?

Dependências de par são pacotes que sua biblioteca espera que a aplicação host forneça. Em outras palavras, ao contrário das dependências normais que são instaladas automaticamente com o pacote da biblioteca, as dependências de par devem ser instaladas e gerenciadas pelo projeto que está utilizando a biblioteca.

Por que Usar Dependências Peer?

A principal razão para usar dependências de par é garantir que a aplicação use uma única instância de uma biblioteca ou framework, como o Angular. Isso é especialmente importante para evitar problemas que surgem de múltiplas instâncias do mesmo pacote, que podem causar conflitos e comportamentos inesperados.

Por exemplo, se a sua biblioteca Angular listar @angular/core como uma dependência regular, o npm ou yarn poderia instalar uma versão separada do Angular especificamente para sua biblioteca, resultando em duas instâncias de @angular/core sendo usadas no mesmo aplicativo. Isso pode levar a erros difíceis de depurar e inconsistências na execução do aplicativo.

Como Configurar Dependências Peer

Para definir dependências de par na sua biblioteca Angular, você deve listar os pacotes relevantes na seção peerDependencies do arquivo package.json da sua biblioteca. Veja como você pode configurar isso:

{
  "name": "my-angular-library",
  "version": "1.0.0",
  "peerDependencies": {
    "@angular/core": "^16.0.0",
    "@angular/common": "^16.0.0",
    "rxjs": "^7.5.0"
  }
}

Passos para Configurar Dependências Peer

1. Identifique Dependências Angular:Verifique quais pacotes Angular sua biblioteca usa e que devem ser compartilhados com a aplicação host. Isso normalmente inclui @angular/core, @angular/common, e qualquer outro pacote do Angular que sua biblioteca utilize diretamente.
2. Defina as Versões Compatíveis:Especifique a faixa de versões compatíveis das dependências de par no package.json. Use caracteres de faixa de versão como ^ ou ~ para permitir atualizações sem introduzir quebras. Certifique-se de testar sua biblioteca com diferentes versões para garantir compatibilidade.
3. Teste a Compatibilidade:Teste sua biblioteca com diferentes versões das dependências de par para verificar a compatibilidade. Isso ajuda a garantir que sua biblioteca funcione corretamente com as versões mais recentes e populares das bibliotecas dependentes.
4. Documente as Requisições:Inclua uma documentação clara sobre quais pacotes precisam ser instalados como dependências de par e quais versões são compatíveis. Isso ajuda os desenvolvedores a configurarem suas aplicações corretamente ao usar sua biblioteca.

Considerações

• Comunidade Angular: Siga as práticas da comunidade Angular ao definir dependências de par para garantir que sua biblioteca seja fácil de usar e integre-se bem em projetos Angular.
• Monitoramento de Atualizações: Esteja atento às atualizações nas bibliotecas Angular e atualize suas faixas de versão de dependências de par conforme necessário para manter a compatibilidade.
• Feedback dos Usuários: Considere o feedback dos usuários de sua biblioteca para ajustar e melhorar a configuração das dependências de par ao longo do tempo.

Ao utilizar dependências peer corretamente, você garante que sua biblioteca Angular funcione em harmonia com a aplicação host, evitando conflitos de versão e proporcionando uma experiência de desenvolvimento mais suave e confiável.