Parte 1: Angular Package Format (APF)

Para garantir a consistência e a integração perfeita de pacotes Angular em diversos cenários, é essencial seguir a especificação do Formato de Pacotes Angular (APF). Esta especificação define a estrutura e o formato dos pacotes npm que são usados por todos os pacotes Angular de primeira linha (como @angular/core, @angular/material, etc.) e pela maioria das bibliotecas Angular de terceiros.

Formato de Pacotes Angular (APF)

APF é uma especificação própria do Angular que descreve como os pacotes npm devem ser estruturados para garantir a máxima compatibilidade e funcionalidade dentro do ecossistema Angular e JavaScript mais amplo. Essa especificação assegura que um pacote funcione de forma integrada com as ferramentas oferecidas pela equipe do Angular, assim como com as ferramentas da comunidade JavaScript em geral.

Por que Especificar um Formato de Pacote? A Importância da Comunicação Eficiente na Frota Estelar

No vasto universo do desenvolvimento JavaScript, existem inúmeras ferramentas e fluxos de trabalho que os desenvolvedores utilizam para construir suas aplicações. Cada ferramenta pode ter suas próprias preferências e requisitos em relação aos pacotes que consome. Algumas ferramentas podem processar as versões mais recentes da linguagem ECMAScript (ES), enquanto outras podem se beneficiar de consumir diretamente uma versão ES mais antiga.

Imagine que cada ferramenta de desenvolvimento é uma nave espacial com seus próprios protocolos de comunicação e sistemas de navegação. Para garantir que sua biblioteca Angular possa se comunicar e interagir com todas essas naves, é crucial que ela utilize um formato de pacote que seja compreendido e aceito por todas elas.

O Angular Package Format: A Linguagem Universal

O Angular Package Format (APF) foi projetado para atender a essa necessidade, oferecendo suporte a todas as ferramentas e fluxos de trabalho comumente utilizados no desenvolvimento Angular e no ecossistema JavaScript em geral. Ele garante que sua biblioteca funcione perfeitamente em diferentes cenários, desde a construção e o desenvolvimento local até a implantação em produção.

Além da compatibilidade, o APF também enfatiza otimizações que resultam em um menor tamanho de carga da aplicação ou em um ciclo de iteração de desenvolvimento mais rápido (tempo de construção). Isso significa que sua biblioteca será mais leve, rápida e fácil de usar, proporcionando uma melhor experiência para os desenvolvedores que a utilizam.

Angular CLI e ng-packagr: Seus Aliados na Comunicação

O Angular CLI e o ng-packagr (uma ferramenta de build utilizada pelo Angular CLI) são seus aliados na criação de pacotes no formato APF. Eles garantem que sua biblioteca seja empacotada de forma correta e otimizada, pronta para ser utilizada em qualquer ambiente de desenvolvimento Angular.

Organização dos Arquivos: A Estrutura Interna da Nave-Mãe Angular

Assim como uma nave espacial possui uma estrutura interna organizada, com diferentes compartimentos e sistemas interconectados, um pacote npm de uma biblioteca Angular também segue um layout de arquivos específico, garantindo que seus componentes e recursos estejam acessíveis e prontos para serem utilizados em outras aplicações.

Um Exemplo Ilustrativo: @angular/core

Para entender melhor essa organização, vamos analisar um exemplo simplificado da estrutura de arquivos do pacote @angular/core:

node_modules/@angular/core
├── README.md  
├── package.json  
├── index.d.ts  
├── esm2022  
│   ├── core.mjs
│   ├── index.mjs
│   ├── public_api.mjs
│   └── testing  
├── fesm2022  
│   ├── core.mjs
│   ├── core.mjs.map
│   ├── testing.mjs
│   └── testing.mjs.map
└── testing  
    └── index.d.ts  

Cada arquivo e diretório desempenha um papel importante na estrutura do pacote:

Entendendo os Formatos de Módulo

• ESM (ECMAScript Modules): O formato de módulo padrão do JavaScript moderno, com suporte a importações e exportações estáticas.
• FESM (Flattened ES Modules): Uma variação do ESM onde todos os módulos são combinados em um único arquivo, facilitando o carregamento em navegadores mais antigos.
• UMD (Universal Module Definition): Um formato de módulo que funciona tanto em ambientes CommonJS quanto em ambientes AMD (Asynchronous Module Definition), além de poder ser incluído diretamente no navegador através de uma tag <script>.

A Importância da Organização

A organização dos arquivos em um pacote npm de biblioteca Angular é fundamental para garantir que os diferentes formatos de módulo e os pontos de entrada estejam claramente definidos e acessíveis. Ao seguir o Angular Package Format, você facilita a utilização da sua biblioteca por outros desenvolvedores e ferramentas, promovendo a colaboração e a interoperabilidade no ecossistema Angular.

package.json: O Coração da sua Biblioteca Angular

package.json: O Coração da sua Biblioteca Angular

No universo das bibliotecas Angular, o arquivo package.json é o coração pulsante que define sua identidade, suas relações com outras bibliotecas e como ela se integra ao ecossistema. É como o núcleo de comando da sua nave espacial, controlando seus sistemas e definindo sua missão.

Metadados Essenciais: A Identidade da sua Nave

O package.json principal contém metadados cruciais sobre sua biblioteca, incluindo:

• Declaração de formato ESM: Informa que o pacote está no formato EcmaScript Module (ESM), o padrão moderno para modularidade em JavaScript.
• Campo “exports”: Define os formatos de código-fonte disponíveis para todos os pontos de entrada da sua biblioteca, permitindo que diferentes ferramentas e ambientes de execução a utilizem de forma otimizada.
• Chaves legadas: Define os formatos de código-fonte disponíveis para o ponto de entrada principal (@angular/core) para ferramentas que ainda não compreendem o campo “exports”. Essas chaves são consideradas obsoletas e podem ser removidas no futuro.
• Declaração de efeitos colaterais: Indica se o pacote contém efeitos colaterais, o que pode influenciar a forma como ele é otimizado por ferramentas de build.

O Campo “exports”: O Mapa da sua Nave

O campo "exports" no package.json é como um mapa detalhado da sua nave espacial, mostrando todos os seus compartimentos e sistemas acessíveis. Ele define os diferentes pontos de entrada da sua biblioteca e os formatos de código-fonte disponíveis para cada um deles.

{
  "exports": {
    ".": { 
      "types": "./index.d.ts",
      "esm2020": "./esm2020/index.mjs",
      "es2020": "./es2020/index.mjs",
      "es2015": "./es2015/index.mjs",
      "node": "./fesm2020/index.mjs",
      "default": "./fesm2015/index.mjs"
    },
    "./testing": {
      "types": "./testing/index.d.ts",
      "esm2020": "./esm2020/testing/testing.mjs",
      "es2020": "./es2020/testing/testing.mjs",
      "es2015": "./es2015/testing/testing.mjs",
      "node": "./fesm2020/testing/testing.mjs",
      "default": "./fesm2015/testing/testing.mjs"
    }
  }
}

Neste exemplo, o campo "exports" define dois pontos de entrada:

• Ponto de entrada principal ("."): Oferece diferentes formatos de código-fonte (ESM2020, ES2020, ES2015) e um arquivo de definição de tipos (index.d.ts).
• Ponto de entrada de teste ("./testing"): Oferece os mesmos formatos de código-fonte para o módulo de teste e seu arquivo de definição de tipos (testing/index.d.ts).

Chaves Legadas: As Relíquias do Passado

Para garantir a compatibilidade com ferramentas mais antigas que ainda não suportam o campo "exports", o package.json também pode conter chaves legadas que definem os formatos de código-fonte disponíveis para o ponto de entrada principal. Essas chaves, como "main", "module" e "typings", são consideradas obsoletas e podem ser removidas no futuro.

Efeitos Colaterais: A Influência da sua Nave

A propriedade "sideEffects" no package.json indica se sua biblioteca possui efeitos colaterais, ou seja, se ela modifica o estado global da aplicação ou realiza outras ações além de simplesmente exportar valores. Essa informação é crucial para que as ferramentas de build possam otimizar o código da sua biblioteca de forma eficiente.

O Coração da sua Biblioteca

O arquivo package.json é o centro de comando da sua biblioteca Angular, definindo sua identidade, suas dependências e como ela se comunica com o mundo. Ao configurá-lo corretamente, você garante que sua biblioteca seja compatível, otimizada e pronta para ser utilizada em qualquer missão espacial Angular.

Declaração ESM: A Linguagem Moderna da sua Biblioteca Angular

No universo do desenvolvimento JavaScript, a modularidade é essencial para organizar e reutilizar código de forma eficiente. O Angular Package Format adota o ESM (ECMAScript Modules) como o padrão de módulo para bibliotecas Angular, garantindo compatibilidade com as ferramentas e os fluxos de trabalho modernos.

O que é ESM?

O ESM é o formato de módulo nativo do JavaScript, introduzido no ECMAScript 6 (ES6). Ele oferece recursos como:

• Importações e exportações estáticas: Permitem que você importe e exporte valores de forma clara e explícita, facilitando a análise estática do código por ferramentas de build e IDEs.
• Carregamento assíncrono: Permite que os módulos sejam carregados sob demanda, melhorando o desempenho da aplicação.
• Suporte a árvores de módulos: Permite que você organize seu código em uma estrutura hierárquica de módulos, facilitando a manutenção e a reutilização.

Declarando o Formato ESM no package.json

Para informar ao Angular CLI e a outras ferramentas que sua biblioteca utiliza o formato ESM, você precisa adicionar a seguinte chave ao seu arquivo package.json:

{
  "type": "module"
}

Essa simples declaração indica que todo o código dentro do pacote utiliza módulos ESM, em vez de módulos CommonJS, que eram o padrão anterior.

Benefícios do ESM

• Compatibilidade: Garante que sua biblioteca seja compatível com as ferramentas modernas do ecossistema JavaScript, como o Angular CLI, o webpack e o Rollup.
• Otimização: Permite que as ferramentas de build realizem otimizações mais avançadas, como tree-shaking (eliminação de código morto) e code splitting (divisão de código), resultando em aplicações menores e mais rápidas.
• Clareza e Organização: A sintaxe de importação e exportação do ESM é mais clara e explícita, facilitando a leitura e a compreensão do código.

Ao declarar o formato ESM no seu package.json, você está sinalizando que sua biblioteca Angular está alinhada com as práticas modernas de desenvolvimento JavaScript. Essa declaração garante a compatibilidade com as ferramentas do ecossistema Angular e permite que sua biblioteca seja otimizada de forma eficiente, resultando em aplicações mais rápidas e performáticas.

github.com/angular/angular-jaSujeito à licença (MIT)

“exports”: O Mapa Estelar da sua Biblioteca Angular

No universo da modularidade JavaScript, o campo "exports" no arquivo package.json é como um mapa estelar detalhado que guia os exploradores (desenvolvedores e ferramentas) através dos diferentes pontos de entrada e formatos de código disponíveis em sua biblioteca Angular. Ele define as rotas de acesso aos tesouros escondidos dentro do seu pacote npm, permitindo que diferentes naves espaciais (aplicações e ferramentas) se conectem e utilizem seus recursos de forma eficiente e segura.

Estrutura do Campo "exports"

Aqui está um exemplo de como o campo "exports" pode ser configurado no package.json de um pacote Angular:

"exports": {
  "./schematics/*": {
    "default": "./schematics/*.js"
  },
  "./package.json": {
    "default": "./package.json"
  },
  ".": {
    "types": "./core.d.ts",
    "esm": "./esm2022/core.mjs",
    "esm2022": "./esm2022/core.mjs",
    "default": "./fesm2022/core.mjs"
  },
  "./testing": {
    "types": "./testing/testing.d.ts",
    "esm": "./esm2022/testing/testing.mjs",
    "esm2022": "./esm2022/testing/testing.mjs",
    "default": "./fesm2022/testing.mjs"
  }
}

Detalhes dos Campos de "exports"

• "." (Entrypoint Primário):
  • Define como o entrypoint principal do pacote (@angular/core) é exposto.
  • "types": Especifica o arquivo de definição de tipos (.d.ts) que deve ser usado pelo TypeScript. Neste caso, é ./core.d.ts.
  • "esm" e "esm2022": Especificam o código ES2022, tanto em arquivos não achatados (./esm2022/core.mjs) quanto achatados (./fesm2022/core.mjs).
  • "default": Define o formato padrão a ser usado quando nenhum formato específico é solicitado. Aqui, é o arquivo ES2022 achatado.
• "./testing" (Entrypoint Secundário):
  • Define como um entrypoint secundário (@angular/core/testing) é exposto.
  • Similar ao entrypoint principal, ele define "types", "esm", "esm2022" e "default" para diferentes formatos de módulo.
• "./schematics/*":
  • Expõe arquivos relacionados a esquemáticos, permitindo que ferramentas específicas acessem esses recursos.
• "./package.json":
  • Expõe o próprio arquivo package.json, que pode ser útil para ferramentas que precisam acessar metadados do pacote.

Importância do Campo "exports"

1. Compatibilidade com Ferramentas Modernas:
   • O campo "exports" permite que ferramentas modernas, como bundlers e resolvers de módulo, compreendam como acessar diferentes partes de um pacote de forma mais eficiente e segura.
2. Resolução de Módulos Segura:
   • Ao definir explicitamente quais módulos e arquivos podem ser acessados, o "exports" ajuda a prevenir acessos não intencionais a partes internas do pacote que não são destinadas ao consumo público.
3. Suporte a Vários Formatos de Módulo:
   • O "exports" permite que um pacote ofereça suporte a múltiplos formatos de módulo (como ES2022 e CommonJS), garantindo que ele possa ser utilizado em uma ampla variedade de ambientes e toolchains.
4. Melhor Desempenho e Redução de Tamanho de Bundle:
   • Ao especificar formatos como "esm2022", os desenvolvedores podem se beneficiar de tree-shaking mais eficaz e de bundles menores, pois o código pode ser otimizadamente achatado e reduzido.
5. Facilita a Migração para Módulos ES:
   • Com o uso do campo "exports", pacotes podem gradualmente migrar para usar módulos ES, ao mesmo tempo em que continuam a oferecer suporte a consumidores que ainda dependem de módulos CommonJS.

O campo "exports" no package.json é uma ferramenta poderosa para desenvolvedores de bibliotecas Angular, permitindo-lhes controlar precisamente como seus pacotes são consumidos. Ele proporciona uma interface clara entre o que é oferecido por um pacote e como ele pode ser utilizado pelos desenvolvedores, garantindo compatibilidade, desempenho e segurança. Seguir as diretrizes do Angular Package Format ao configurar "exports" ajuda a assegurar que um pacote Angular seja robusto e confiável em qualquer cenário de uso.

Chaves Legadas de Resolução: Uma Ponte para o Passado

No universo em constante evolução do desenvolvimento JavaScript, a compatibilidade com versões anteriores é um desafio constante. O Angular Package Format, embora adote o moderno campo "exports" para definir os pontos de entrada da sua biblioteca, também oferece suporte a chaves legadas de resolução para garantir a compatibilidade com ferramentas mais antigas que ainda não compreendem o novo padrão.

O Legado da Resolução de Módulos

Antes da introdução do campo "exports", as ferramentas de build e os ambientes de execução JavaScript utilizavam um conjunto de chaves predefinidas no arquivo package.json para determinar como resolver os módulos de uma biblioteca. Algumas dessas chaves legadas incluem:

• "main": Define o ponto de entrada principal da biblioteca para ambientes CommonJS.
• "module": Define o ponto de entrada principal da biblioteca para ambientes que suportam ESM, mas ainda não compreendem o campo "exports".
• "typings": Define o caminho para o arquivo de definição de tipos (.d.ts) da biblioteca.

Exemplo: Chaves Legadas em @angular/core

No pacote @angular/core, as chaves legadas são definidas da seguinte forma:

{
  "module": "./fesm2022/core.mjs",
  "typings": "./core.d.ts",
}

Essas chaves informam às ferramentas que o ponto de entrada principal da biblioteca para ambientes ESM é o arquivo fesm2022/core.mjs, e que o arquivo de definição de tipos é core.d.ts.

O Futuro das Chaves Legadas

Embora as chaves legadas ainda sejam suportadas pelo Angular Package Format, elas são consideradas obsoletas e podem ser removidas em versões futuras. À medida que mais ferramentas e ambientes de execução adotam o campo "exports", a necessidade de manter essas chaves legadas diminuirá.

Uma Ponte para o Futuro

As chaves legadas de resolução são como uma ponte que conecta o passado ao presente, garantindo a compatibilidade da sua biblioteca Angular com ferramentas mais antigas. No entanto, é importante lembrar que essa ponte é temporária e que o futuro da modularidade em JavaScript está no campo "exports".

Efeitos Colaterais: A Influência da sua Biblioteca no Universo Angular

No ecossistema Angular, as bibliotecas desempenham um papel crucial, fornecendo funcionalidades e recursos reutilizáveis para diversas aplicações. No entanto, algumas bibliotecas podem ter efeitos colaterais, ou seja, podem modificar o estado global da aplicação ou realizar outras ações além de simplesmente exportar valores.

Imagine que sua biblioteca é uma nave espacial que, ao ser acoplada a outra nave, pode causar alterações no sistema de navegação ou na configuração dos motores. Esses efeitos colaterais, embora possam ser úteis em alguns casos, também podem levar a conflitos e comportamentos inesperados se não forem gerenciados adequadamente.

A Bandeira sideEffects: Sinalizando a Presença de Efeitos Colaterais

Para informar às ferramentas de build se sua biblioteca possui efeitos colaterais, você pode utilizar a propriedade "sideEffects" no arquivo package.json.

{
  "sideEffects": false 
}

Neste exemplo, estamos declarando que nossa biblioteca não possui efeitos colaterais. Essa informação é crucial para que as ferramentas de build, como o webpack e o Rollup, possam otimizar o código da sua biblioteca de forma mais eficiente.

O Impacto dos Efeitos Colaterais na Otimização

• Tree-shaking: Se sua biblioteca não possui efeitos colaterais, as ferramentas de build podem utilizar uma técnica chamada tree-shaking para remover código não utilizado do pacote final. Isso reduz o tamanho da sua biblioteca e melhora o desempenho da aplicação.
• Ordem de Importação: Se sua biblioteca possui efeitos colaterais, a ordem em que ela é importada em relação a outras bibliotecas pode ser importante. As ferramentas de build precisam garantir que os efeitos colaterais sejam executados na ordem correta para evitar problemas.

Quando Declarar Efeitos Colaterais

A maioria dos pacotes Angular não deve depender de efeitos colaterais de nível superior e, portanto, deve incluir a declaração "sideEffects": false. No entanto, existem alguns casos em que sua biblioteca pode precisar de efeitos colaterais, como:

• Estilos Globais: Se sua biblioteca define estilos CSS globais que afetam toda a aplicação, ela possui efeitos colaterais.
• Polyfills: Se sua biblioteca inclui polyfills para fornecer suporte a navegadores mais antigos, ela possui efeitos colaterais.
• Inicialização Global: Se sua biblioteca precisa executar algum código de inicialização ao ser importada, ela possui efeitos colaterais.

Nesses casos, você deve definir "sideEffects": true ou fornecer um array com os caminhos dos arquivos que possuem efeitos colaterais.

Uma Navegação Segura e Eficiente

Ao declarar corretamente os efeitos colaterais da sua biblioteca, você permite que as ferramentas de build otimizem seu código de forma mais eficiente, resultando em aplicações menores e mais rápidas. Além disso, você evita problemas de compatibilidade e garante que sua biblioteca funcione harmoniosamente com outras naves no universo Angular.

Pontos de Entrada e Divisão de Código: Organizando os Compartimentos da sua Nave Espacial

No universo Angular, a eficiência e a performance são cruciais para uma navegação tranquila e bem-sucedida. Para garantir que sua biblioteca Angular seja leve e rápida, o Angular Package Format utiliza o conceito de pontos de entrada e divisão de código, permitindo que você organize e carregue apenas os recursos necessários em cada momento.

Imagine que sua biblioteca é uma nave espacial com diferentes compartimentos, cada um contendo ferramentas e recursos específicos. Em vez de carregar todos os compartimentos de uma só vez, o que tornaria a nave pesada e lenta, você pode utilizar pontos de entrada para acessar cada compartimento individualmente, carregando apenas o que é necessário para cada missão.

Pontos de Entrada: As Portas de Acesso à sua Nave

Os pacotes no Angular Package Format contêm um ponto de entrada principal e zero ou mais pontos de entrada secundários. Esses pontos de entrada desempenham várias funções importantes:

• Definem os especificadores de módulo: Os usuários utilizam esses especificadores para importar o código da sua biblioteca, como @angular/core e @angular/core/testing.
• Organizam os símbolos em grupos lógicos: Os usuários percebem os pontos de entrada como grupos distintos de símbolos, cada um com um propósito ou capacidade específica.
• Isolam APIs especiais: APIs utilizadas para fins específicos, como testes, podem ser separadas do ponto de entrada principal para reduzir a chance de serem usadas acidentalmente ou incorretamente.
• Definem a granularidade do carregamento lazy (code splitting): Muitas ferramentas de build modernas só conseguem dividir o código em nível de módulo ES. O Angular Package Format utiliza principalmente um único módulo ES “achatado” por ponto de entrada, o que significa que a maioria das ferramentas não consegue dividir o código de um único ponto de entrada em vários chunks de saída.

A Regra de Ouro: Granularidade

A regra geral para pacotes APF é usar pontos de entrada para os menores conjuntos de código logicamente conectados possíveis. Por exemplo, o pacote Angular Material publica cada componente ou conjunto de componentes como um ponto de entrada separado – um para o botão, um para as abas, etc. Isso permite que cada componente Material seja carregado de forma lazy (sob demanda), se desejado, otimizando o desempenho da aplicação.

Nem todas as bibliotecas exigem essa granularidade. A maioria das bibliotecas com um único propósito lógico deve ser publicada como um único ponto de entrada. O @angular/core, por exemplo, usa um único ponto de entrada para o tempo de execução, porque o tempo de execução do Angular geralmente é usado como uma única entidade.

Resolução de Pontos de Entrada Secundários: O Mapa da Nave

Os pontos de entrada secundários podem ser resolvidos através do campo "exports" do arquivo package.json do pacote. Esse campo define os caminhos para os diferentes pontos de entrada e os formatos de código disponíveis para cada um deles.

Uma Nave Espacial Organizada e Eficiente

Com o uso inteligente de pontos de entrada e a divisão de código, você garante que sua biblioteca Angular seja leve, rápida e fácil de usar. Ao organizar seus recursos em módulos lógicos e permitir o carregamento lazy, você otimiza o desempenho da sua aplicação e proporciona uma experiência de usuário superior.

README.md: O Cartão de Boas-Vindas da sua Biblioteca

No universo das bibliotecas Angular, o arquivo README.md é como um cartão de boas-vindas que apresenta sua criação aos exploradores (desenvolvedores) que desejam utilizá-la. Ele fornece informações essenciais sobre a biblioteca, como sua finalidade, recursos, instalação e uso, guiando os usuários em sua jornada de exploração.

O Formato Markdown: A Linguagem da Documentação

O arquivo README.md utiliza o formato Markdown, uma linguagem de marcação leve e fácil de ler que permite criar documentos formatados com títulos, listas, links, imagens e outros elementos. Essa linguagem é amplamente utilizada em projetos de código aberto, tornando-a familiar para a maioria dos desenvolvedores.

Conteúdo do README: O Guia de Bordo

O arquivo README.md da sua biblioteca deve conter informações essenciais para os usuários, como:

• Nome e Descrição: Apresente o nome da sua biblioteca e uma breve descrição de sua finalidade e recursos.
• Instalação: Explique como instalar a biblioteca usando o npm ou yarn.
• Uso: Forneça exemplos de código e instruções detalhadas sobre como utilizar os componentes, serviços e outros elementos da sua biblioteca.
• Configuração: Se sua biblioteca requer alguma configuração adicional, explique como realizá-la.
• Contribuição: Incentive os desenvolvedores a contribuir com sua biblioteca, fornecendo diretrizes para a abertura de issues e pull requests.
• Licença: Informe a licença de código aberto da sua biblioteca, permitindo que outros desenvolvedores a utilizem e contribuam para seu desenvolvimento.

Exemplo: README do @angular/core

O pacote @angular/core do Angular fornece um exemplo simples e direto de um arquivo README.md:

Angular
=======

The sources for this package are in the main [Angular](https://github.com/angular/angular) repo. 
Please file issues and pull requests against that repo.

License: MIT

Um Cartão de Boas-Vindas Eficaz

Um arquivo README.md bem escrito e completo é essencial para o sucesso da sua biblioteca Angular. Ele fornece aos usuários as informações necessárias para instalar, configurar e utilizar sua biblioteca de forma eficiente, além de incentivar a colaboração e o crescimento da comunidade em torno do seu projeto.

Compilação Parcial: Preparando sua Biblioteca para Múltiplas Missões

No universo Angular, a compatibilidade entre bibliotecas e aplicações é essencial para garantir um funcionamento harmonioso e livre de conflitos. Para alcançar essa compatibilidade, o Angular Package Format utiliza um modo de compilação especial chamado “compilação parcial”, que permite que sua biblioteca seja utilizada em diferentes versões do Angular.

O Que é a Compilação Parcial?

A compilação parcial é um modo de compilação do ngc (compilador Angular) que produz código Angular compilado que não está vinculado a uma versão específica do Angular runtime, ao contrário da compilação completa utilizada para aplicações, onde as versões do compilador e do runtime Angular devem corresponder exatamente.

Imagine que sua biblioteca é um módulo versátil, capaz de se adaptar a diferentes modelos de naves espaciais Angular. A compilação parcial garante que esse módulo seja compatível com uma ampla gama de versões do Angular, permitindo que ele seja utilizado em diferentes missões e projetos.

Configurando a Compilação Parcial

Para compilar seu código Angular parcialmente, utilize a flag compilationMode na propriedade angularCompilerOptions do seu arquivo tsconfig.json:

{
  // ...
  "angularCompilerOptions": {
    "compilationMode": "partial" 
  }
}

Compilação Parcial: Preparando sua Biblioteca para Múltiplas Missões

No universo Angular, a compatibilidade entre bibliotecas e aplicações é essencial para garantir um funcionamento harmonioso e livre de conflitos. Para alcançar essa compatibilidade, o Angular Package Format utiliza um modo de compilação especial chamado “compilação parcial”, que permite que sua biblioteca seja utilizada em diferentes versões do Angular.

O Que é a Compilação Parcial?

A compilação parcial é um modo de compilação do ngc (compilador Angular) que produz código Angular compilado que não está vinculado a uma versão específica do Angular runtime, ao contrário da compilação completa utilizada para aplicações, onde as versões do compilador e do runtime Angular devem corresponder exatamente.

Imagine que sua biblioteca é um módulo versátil, capaz de se adaptar a diferentes modelos de naves espaciais Angular. A compilação parcial garante que esse módulo seja compatível com uma ampla gama de versões do Angular, permitindo que ele seja utilizado em diferentes missões e projetos.

Configurando a Compilação Parcial

Para compilar seu código Angular parcialmente, utilize a flag compilationMode na propriedade angularCompilerOptions do seu arquivo tsconfig.json:

JSON

{
  // ...
  "angularCompilerOptions": {
    "compilationMode": "partial" 
  }
}

Use o código com cuidado.

O Linker Angular: A Ponte entre a Biblioteca e a Aplicação

O código da biblioteca compilado parcialmente é então convertido em código totalmente compilado durante o processo de build da aplicação pelo Angular CLI. Essa conversão é realizada pelo Linker Angular, uma ferramenta que garante a compatibilidade entre a biblioteca e a aplicação, mesmo que elas tenham sido construídas com versões diferentes do Angular.

Se seu processo de build não utiliza o Angular CLI, você pode utilizar o Linker Angular como um plugin do Babel para realizar essa conversão. Consulte o guia “Consumindo código partial-ivy fora do Angular CLI” para obter mais informações.

Conclusão da Primeira Parte: O Formato Angular em Detalhes

A compilação parcial é uma inovação significativa no formato de pacotes do Angular, oferecendo uma solução robusta para o desenvolvimento e distribuição de bibliotecas Angular.
Ela facilita a manutenção e evolução de bibliotecas, permitindo que suportem múltiplas versões do Angular sem a necessidade de recompilação completa para cada atualização do framework. Com a configuração correta, desenvolvedores de bibliotecas podem garantir que suas soluções sejam flexíveis, eficientes e compatíveis com uma ampla gama de aplicações Angular.

Agora que você compreendeu a importância da compilação parcial e como configurá-la, continue conosco na segunda parte desta série, onde exploraremos as otimizações e práticas recomendadas para o formato de pacotes Angular, incluindo flattening de módulos ES, o uso do sinalizador “sideEffects”, e muito mais!