Angular esquemas para bibliotecas: mantendo seus projetos atualizados
O que são esquemas angulares e quais são seus benefícios? Aprenda como melhorar sua biblioteca com Angular esquemas, aproveitando ao máximo ng add e ng update.
V Slavov
13min read
Angular esquemas já existem há algum tempo e acho que a maioria de nós se acostumou a trabalhar com eles e aproveitar seus muitos benefícios. Desde a execução de um simples ng novo até a criação de esquemas complexos que automatizam o fluxo de trabalho e a configuração do projeto, o mecanismo de esquemas é uma grande parte do ciclo de vida de qualquer aplicativo Angular.
Mas que tal uma biblioteca Angular?
Na Infragistics, temos muito orgulho em desenvolver e manter nossa biblioteca de componentes Angular de código aberto. Mas com a biblioteca ganhando cada vez mais usuários e a natureza em constante evolução do Angular, precisávamos fornecer uma maneira fácil de manter os projetos atualizados. É aqui que, como acontece com a maioria das coisas Angular, os esquemas entram em jogo.
ng add, ng update and more
Neste blog, mostraremos como configurar sua biblioteca para que ela aproveite ao máximo os comandos ng add e ng update da CLI Angular. Faremos isso definindo coleções esquemáticas de uma maneira específica.
Disclaimer:
Para aproveitar ao máximo este post, o ideal é que você já esteja familiarizado com os conceitos básicos de Angular esquemas e possa estar interessado em alguns dos outro Legal Posts no Medium.
Para pegar emprestado de um artigo recente da angular.io:
Um esquema é um gerador de código baseado em modelo que suporta lógica complexa. É um conjunto de instruções para transformar um projeto de software gerando ou modificando código. Os esquemas são empacotados emcoleçõese instalados com o npm.
O que são Angular Esquemas?
Os esquemassãoo bloco de construção daCLI Angular. Eles são conjuntos executáveis de instruções que executam manipulações em arquivos existentes ou geram arquivos/conteúdo.Se você é um desenvolvedor Angular, provavelmente já usou criou um componente executando:
ng g c [component name]
Os esquemas são uma grande parte do ecossistema Angular e entendê-los melhor pode melhorar muito a sua vida e a de seus usuários.
Veremos um rápido tutorial esquemático angular para que você possa se familiarizar com o básico antes de nos aprofundarmos.
Criação Angular esquemas
Você pode começar rapidamente a criar seus próprios esquemas aproveitando o próprio cli esquemático do Angular.
Basta executar o seguinte para instalá-lo globalmente:
npm install -g @angular-devkit/schematics-cli
Em seguida, crie um esquema de exemplo em branco pronto para uso chamando:
schematics blank --name=intro-schematic
Se você examinar os arquivos gerados, poderá examiná-los para descobrir como exatamente os esquemas são expostos aos usados.
- No arquivo package.json, você pode ver que há uma propriedade "esquemática", apontando para um "collection.json"
- Seguindo esse caminho, você pode inspecionar esse arquivo – é um arquivo de .json bastante padrão, com uma coisa importante – uma propriedade "esquemática", que é uma lista de todos os esquemas expostos aos usuários.
Logo após executar o comando de exemplo acima, a lista deve ter apenas uma entrada – "Esquemas de introdução". A entrada contém uma breve descrição e uma referência a uma "fábrica" – é aqui que o corpo do esquema é definido. - No referido arquivo 'index.ts', o "corpo" dos esquemas é definido – uma 'Regra' que será executada no contexto do projeto consumidor e onde toda a sua lógica personalizada residirá
Agora você pode chamá-lo de exemplo de fora do projeto chamando:
ng g [path-to-collection.json]:intro-schematics
Mas essa não é a única maneira de chamar esquemas. Angular expuseram"ganchos" C Onvenient para desenvolvedores que podem automatizar ainda mais a experiência de seus usuários.
Angular Pontos de entrada esquemáticos
Além de chamar um Angular esquema com o usual
ng g my-custom-library:schematics [args]
A CLI do Angular também fornece dois outros pontos de entrada para seus fluxos de trabalho de biblioteca personalizados – ng add e ng update. Se você não estiver familiarizado com esses comandos ng, poderá aprender mais sobre eles aqui e aqui. Em um aplicativo Angular que está usando sua biblioteca, eles funcionam de forma semelhante ao gancho de pós-instalação do npm. Eles são chamados automaticamente pela CLI do Angular– ao chamar
ng add my-custom-library
Ou
ng update my-custom-library
respectivamente.
Migration Schematics
Um dos principais benefícios de usar a CLI do Angular é atualizar as dependências do pacote, minimizando a necessidade de contornar manualmente as alterações ou depreciações significativas. Tudo isso pode ser automatizado definindo esquemas de migração para sua biblioteca!
Um esquema de migração é executado sempre que uma versão mais recente de sua biblioteca é adicionada ao aplicativo consumidor por meio de ng update your-custom-library. Em um esquema de migração, você pode não apenas definir quais alterações seus esquemas de migração devem executar, mas também especificar o escopo da migração (qual versão ela afeta).
Adding migration schematics
A definição de esquemas de migração é feita de maneira semelhante à definição de um esquema normal — você precisa criar uma função que retorne uma regra. Essa regra pode manipular a árvore de trabalho, registrar coisas e / ou qualquer outra coisa que você possa fazer com Javascript. A parte mais específica é garantir que a CLI do Angular chame o esquema no gancho de atualização ng.
Defining the schematics collection
Primeiro, você precisa definir um arquivo collection.json esquemático. O nome não importa. No caso da nossa biblioteca, nós o nomeamos migration-collection.json, pois temos várias coleções esquemáticas e isso torna mais fácil dizer qual é qual.
A estrutura do seu collection.json deve ser semelhante a esta:
{
"schematics": {
"migration-01": {
// Migration name, no strict naming, must be unique
"version": "2.0.0", // The target version
"description": "Updates my-custom-library from v1 to v2", // A short description, not mandatory
"factory": "./update-2" // The update schematic factory
}
,
"migration-02": {
"version": "3.0.0",
"description": "Updates my-custom-library from v2 to v3",
"factory": "./update-3"
}
,
...
}
}
O objeto schematics hospeda todas as suas definições de esquemas de atualização. Cada definição está sob uma propriedade nomeada (que deve ser única) e, para cada uma, você deve especificar a versão na qual as "alterações" são introduzidas e a fábrica do esquema que será executado na árvore de trabalho. O atributo version é usado para determinar quando o esquema precisa ser executado.
Por exemplo, digamos que você tenha um aplicativo consumindo my-custom-library@1.0.0. Com a definição de esquemas acima, se você executasse ng update my-custom-library@2.0.0, apenas o esquema definido "version": "6.0.0"seria executado. Ao executar
ng update my-custom-library@3.0.0
Os esquemas de migração 2.0.0 e 3.0.0 seriam executados.
A definição real dos esquemas de migração (para v2.0.0, por exemplo) está em ./update-2/index.ts pode ser como qualquer outro esquema. Uma implementação muito básica seria esta:
export default function(): Rule {
return (host: Tree, context: SchematicContext) => {
const version = `1.0.0` // You can get this dynamically from the package.json
context.logger.info(`Applying migration for custom library to version ${version}`);
return host;
};
}
Você pode encontrar a definição de um dos esquemas de migração mais recentes em igniteui-angular aqui.
Isenção de responsabilidade: Na implementação esquemática de nossa biblioteca, estamos fazendouso intensodo serviço de linguagem TypeScript para manipular arquivos. Sinto muito por não entrar em detalhes, mas isso justificaria um post próprio. Se você tiver alguma dúvida, sinta-se à vontade para entrar em contato nos comentários e tentarei responder da melhor maneira possível.
Anexando a coleção de esquemas ao gancho ng-update
Depois que o collection.json de migração é criado e os esquemas de migração são definidos, tudo o que resta é anexá-los corretamente ao gancho ng-update. Tudo o que você precisa fazer para isso é ir até o package.json da sua biblioteca e adicionar a seguinte propriedade "ng-update":
{
"name": "my-custom-library",
"version": "2.0.0",
... "ng-update": {
"migrations": "./migrations/migration-collection.json"
}
}
É isso! Agora, toda vez que alguém executa ng update my-custom-library, a CLI do Angular e os esquemas que você elaborou cuidadosamente cuidarão de quaisquer alterações ou depreciações incômodas que um usuário possa perder!
ng-add
O outro ponto de entrada útil que a CLI do Angular fornece é o gancho ng add. Quando você define um esquema ng add, ele é executado automaticamente assim que um usuário adiciona sua biblioteca ao projeto de consumo executando
ng add [custom-library]
Você pode pensar nisso como algo semelhante ao gancho de pós-instalação do npm.
Definir um esquema ng add para sua biblioteca é a melhor maneira de garantir que seus usuários tenham uma experiência inicial fácil com ele. Através dos esquemas, você pode automatizar algumas configurações iniciais obrigatórias, adicionar/atualizar pacotes ou simplesmente registrar um grande "obrigado!" a todos os seus usuários! 🙂
Em nossa biblioteca, adicionamos um esquema ng add que instala nossa CLI IgniteUI no espaço de trabalho do projeto para que os usuários possam aproveitar ao máximo nosso conjunto de componentes por meio de nossa CLI.
Fazemos algumas transformações iniciais no espaço de trabalho (adicionando um arquivo de .json personalizado necessário para que nossa CLI seja executada), adicionamos alguns estilos e pacotes (para que nossos componentes sejam renderizados corretamente) e até chamamos alguns esquemas (schematiception!) de nossa CLI, onde descarregamos parte da lógica específica da CLI Angular.
Tudo isso (e muito mais!) pode ser feito automaticamente, simplesmente chamando ng add – esse, na minha opinião, é o verdadeiro charme da CLI Angular.
Criar esquema ng-add
Para adicionar um esquema ng add à sua biblioteca, primeiro você precisa defini-lo. Como acontece com qualquer outro esquema, ele precisa fazer parte de uma coleção. Se o seu projeto já expõe esquemas, você pode adicioná-lo à coleção existente com o nome ng-add. Caso contrário, você pode criar a coleção do zero:
Na pasta raiz da sua biblioteca:
mkdir schematics && cd schematics echo blank > collection.json mkdir ng-add
Abra o collection.json recém-criado, modifique-o para apontar para a definição do esquema ng-add
{
"$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
"schematics": {
"ng-add": {
"description": "Installs the needed dependencies onto the host application.",
"factory": "./ng-add/index",
"schema": "./ng-add/schema.json"
}
}
}
Em schematics/ng-add/index.ts você pode criar a implementação do esquema ng-add da mesma forma que faria com qualquer outro esquema. Por exemplo, para exibir uma mensagem simples de "Obrigado!" para seus usuários, você pode fazer o seguinte:
export default function (options: Options): Rule {
return (_tree: Tree, context: SchematicContext) => {
context.logger.info(`Thank you for using our custom library! You're great!`);
};
}
A implementação do esquema ng-add do IgniteUI Angular pode ser encontrada aqui.
Incluir em package.json
Depois de concluir a implementação do esquema, você deve incluir a definição de coleção no package.json da biblioteca. Se sua biblioteca já expõe uma coleção de esquemas, você tem isso coberto! Caso contrário, você só precisa adicionar uma propriedade "schematics", apontando para a localização do seu collection.json recém-criado:
{
"project": "my-custom-library",
"version": "2.0.0",
... "schematics": "./schematics/collection.json"
}
Você pode encontrar essa parte da configuração refletida em nosso repositório de biblioteca.
Bundling your schematics
Você deve certificar-se de que os esquemas definidos (migrações e coleções ng-add) sejam enviados corretamente com seu pacote de biblioteca. Para fazer isso, você precisará definir uma tarefa de compilação separada para seus esquemas (executada após a execução da tarefa de compilação principal), com outDir especificado para apontar para o local apropriado na pasta dist do seu projeto (para que os arquivos collection.json tenham os mesmos caminhos, em relação ao package.json). Por fim, você precisará copiar explicitamente todos os arquivos excluídos pelo compilador (por exemplo, todos os arquivos .json!).
Supondo que o diretório de saída para seus projetos compilados seja .. /dist (para que os arquivos empacotados do seu projeto estejam em .. /dist/my-custom-lib/) a saída de compilação do seu esquema terá que ser .. /dist/schematics (para a coleção de esquemas padrão, contendo ng-add) e .. /dist/migrations (para a coleção de esquemas de migração)
Para fazer isso, você deve primeiro definir um arquivo tsconfig.json para suas coleções de esquemas (localizados em ./schematics/ ou ./migrations, respectivamente). Por exemplo, o conteúdo do arquivo para a coleção de esquemas principais (./schematics) seria algo assim:
{
"compilerOptions": {
"target": "es6",
"module": "commonjs",
"sourceMap": false,
"composite": true,
"declaration": true,
"outDir": "../../../dist/my-custom-lib/schematics/"
}
}
Em seguida, no package.json do seu projeto, defina um script que construa seus esquemas e outro que copie os arquivos:
{
"name": "my-custom-library",
...
"scripts": {
"build:schematics": "tsc --project migrations/tsconfig.json",
"copy:schematics:collection": "cp --parents migrations/*/collection.json ../../dist/my-custom-lib/"
},
...
}
O mesmo vale para as migrações – um script separado para compilação do TypeScript e para copiar os arquivos.
Para o repositório Ignite UI for Angular, é possível verificar os links para ver a implementação da coleção de esquemas padrão e as migrações. (Como estamos usando o gulp como uma ferramenta de compilação, definimos tarefas separadas para copiar os arquivos collection.json)
Executando esquemas ng-add e ng-update localmente
Antes de publicar seu pacote de biblioteca com sua nova e brilhante atualização ng e ng adicionar funcionalidade, talvez você queira verificar se os esquemas estão executando as transformações adequadas no local de trabalho. Como, no final, ambas são apenas implementações esquemáticas básicas, você pode executá-las como faria com qualquer outra - usando ng g!
Depois de criar seus arquivos de biblioteca e esquemas + migrações, você pode entrar no diretório de saída especificado (onde o package.json do pacote está localizado) e empacotá-lo
npm pack
Running ng-add
Para verificar como seu comando ng-add está sendo executado dentro de um novo projeto, você pode fazer o seguinte:
Criar um novo projeto usando a CLI do Angular
ng g my-test-project --routing=true
Depois que o projeto for criado, você poderá ir para a pasta do projeto e instalar seu pacote manualmente a partir do arquivo .tgz:
npm i my-custom-library.tgz
Then, simply run
ng g my-custom-library:ng-add
e revise a mudança no local de trabalho assim que terminar - é isso que o ng-add do seu pacote fará!
Running migrations
Para testar migrações, você pode seguir as mesmas etapas acima, embora tenha que especificar o caminho para o collection.json de esquemas de migração (pois é diferente da coleção de esquemas padrão do projeto).
Digamos que seu esquema de migração mais recente que você deseja testar seja chamado update-1. Depois de instalar manualmente o arquivo .tgz, basta executar:
ng g "./node_modules/my-custom-library/migration-collection.json:update-1"
Isso aplicará todas as alterações no local de trabalho que seu esquema de migração mais recente aplicaria.
Considerações finais
Espero que este post tenha sido útil para você e tenha esclarecido algumas coisas sobre Angular funcionalidade ng add e ng update da CLI. Os esquemas da Angular agora são uma parte sólida do ecossistema de seus projetos e certamente continuarão melhorando. Com cada vez mais desenvolvedores usando-os e aumentando a conscientização sobre eles, agora é um ótimo momento para as bibliotecas começarem a adotar esquemas. Por que não automatizar você e seus usuários, as preocupações de distância? 🙂
Se você tiver alguma dúvida, sinta-se à vontade para entrar em contato nos comentários.
Thanks for reading!