Schematics: Criando um gerador de códigos com Angular — Parte 1

O dia em que cansamos de fazer telas de cadastro

Este post é o primeiro de uma série sobre o Schematics, que vai abordar desde os conceitos até termos um gerador de código funcional. Leia a parte 2 aqui.

Um sábio me disse algumas dezenas de vezes que se você passa grande parte do seu tempo criando telas de cadastro, é porque você está fazendo alguma coisa errada.

O famoso Scaffolding, que era muito popular em frameworks MVC, acabou caindo em desuso ao longo do tempo. Bibliotecas como Formly são muito boas, mas deixam o template “engessado” demais. Pois bem, depois de criarmos mais um CRUD no nosso projeto, veio a pergunta:

Pra que diabos estamos criando telas de cadastro se estamos trabalhando com inovação?

Obviamente nós precisávamos das telas, mas não fazia sentido criá-las do zero. Então, resolvemos nos aventurar criando nosso primeiro Schematics.

Como o Schematics funciona

No Schematics, você não faz alterações direto no sistema de arquivos. Ao invés disso, você modifica um elemento chamado Tree.

A Tree é uma estrutura de dados que contém uma base (com os arquivos que já existem) e uma área de staging (uma lista de alterações a serem aplicadas na base). Qualquer semelhança com o git não é mera coincidência. Cada alteração que você faz é realizada em staging, e somente no final elas são aplicadas na base.

Isso permite que o seu schematic suporte dry-runs sem que você se preocupe com a implementação. Em caso de erros durante a execução, os seus arquivos não serão afetados também.

Criando o seu primeiro Schematics

Instale o CLI globalmente usando o seguinte comando:

npm install -g @angular-devkit/schematics-cli

E em seguida, crie o projeto:

schematics blank --name=my-schematics

Pronto! Seu projeto está criado. Mãos à obra!

Collections

Uma collection nada mais é do que um coleção de schematics. A do Angular, por exemplo, chama-se @schematics/angular que possui os geradores para component, module, etc. A do Nx é a @nrwl/schematics.

Uma collection também pode estender outra collection. Assim, você pode usar os schematics do Angular junto aos seus sem precisar ficar alternando entre eles.

O arquivo collection.json é o arquivo que define a nossa collection:

O $schema contém o schema definindo o formato do nosso arquivo. O nosso schematic padrão está na chave schematics, que define cada schematic da nossa collection. Por padrão, você vai ver um schematic chamado my-schematic, apontando pra factory que é a função myComponent do arquivo src/my-schematics/index.ts. Ele é a nossa RuleFactory.

RuleFactory

RuleFactory é uma função que define umaRule. Nós a podemos comparar à uma planta do que nós queremos fazer. Ela define os passos que o nosso schematic precisa pra funcionar.

A nossa RuleFactory padrão vem com o seguinte conteúdo:

Rule é uma função que recebe a Tree e retorna uma outra Tree. Um schematic pode ter uma ou mais Rules, e são nelas que tudo acontece. Como a factory aponta pra função mySchematics, ela é o ponto de entrada da execução.

O objeto _options contém os inputs que foram definidos no schema, mas vamos aprofundar um pouco mais sobre ele no próximo artigo.

Como nossa função simplesmente está retornando a Tree que ela recebe, vamos deixar a coisa um pouco mais interessante:

Agora temos uma função que cria um arquivo com o nome passado via parâmetro name e o conteúdo world. Caso nenhum nome seja passado, ela cria um arquivo com o nome hello.

Voilà! Acabamos de criar o nosso primeiro schematic. Para isso, precisamos compilar os arquivos typescript:

npm run build

E em seguida executá-lo:

schematics .:my-schematics --name=awesome

O terminal vai te informar que um arquivo chamado awesome foi criado na raiz do projeto. Não se preocupe. O arquivo não está lá porque por padrão o CLI é executado em modo debug. Se você quiser ver o arquivo, basta executar o mesmo comando passando --dry-run=false.

Adicionando o Schematic ao seu projeto

Vamos criar um projeto Angular padrão:

ng new my-project

Navegue para a pasta do seu projeto adicione o Schematic que a gente acabou de criar via npm link:

cd my-project
npm link <path-to-schematics-project>

Troque o <path-to-schematics-project> pelo caminho do seu projeto schematics. No meu caso os dois projetos estão no mesmo diretório, então eu executei

npm link ../my-schematics

Feito isso, basta executar o schematic via Angular CLI:

ng g my-schematics:my-schematics --name=awesome

Pronto! O arquivo awesome foi criado na raiz do seu projeto. Pode conferir o conteúdo.

Por mais que seja um exemplo pequeno, pudemos ver que com alguns passos nós podemos criar um gerador totalmente funcional que pode ser utilizado em nossa aplicação. No próximo artigo, vamos estruturar o nosso schema para criarmos o gerador de código.

Continua aqui.