Angular: evolua a documentação do seu Design System com Nx e Storybook

Criando biblioteca input - Apresentação

Você deseja evoluir seu Design System com o Storybook e publicá-lo para que todo mundo possa vê-lo? Boas-vindas a este curso de Angular com o Antônio Evaldo.

Audiodescrição: Antônio se considera um homem branco, com bigode e cavanhaque, utiliza óculos com armação arredondada, tem cabelos cacheados, escuros e volumosos. Atrás dele, há uma parede com três pequenos pôsteres de desenhos de animação japonesa iluminada pelas cores rosa e azul.

O projeto

Neste curso, vamos explorar um projeto sensacional. Com ele aberto no navegador, já estamos com o Storybook publicado. Ele possui uma página de boas-vindas indicando que é o Design System da Alfabit, uma empresa fictícia da qual fazemos parte, e inclui links para outras páginas. Ao clicar no link de "botão", somos redirecionados para o componente de botão que já estava publicado. Além disso, inserimos um novo componente, o de "Input".

Este componente está muito bem elaborado, com seu bloco de controle e seus Stories. Vamos trabalhar em todos esses Stories ao longo do curso. Nossa documentação do Storybook está mais caprichada, com documentações específicas para seções, categorias de moléculas, átomos e até mesmo para as cores utilizadas pelo Design System da Alfabit. A parte visual está muito bonita, mostrando todas as escalas de cinza, do tema azul e do tema violeta.

Vamos publicar o projeto, e qualquer pessoa no mundo poderá acessá-lo através de um endereço na web. Utilizaremos o Chromatic, uma ferramenta que não só nos ajuda a publicar o Storybook, mas também permite realizar testes visuais.

Os testes visuais são essenciais para capturar problemas visuais nos componentes, possibilitando discussões com o time antes da publicação.

O que vamos aprender?

Primeiro, criaremos a biblioteca de "Input" e trabalharemos em suas variantes. Em seguida, criaremos novas documentações para as seções do Storybook, utilizando MDX e JSX. Depois, utilizaremos o Chromatic para publicar o Storybook e realizar testes visuais.

Em seguida, publicaremos efetivamente o componente de "Input" e republicaremos o componente de botão, enquanto avançamos no NX Release e utilizamos commits convencionais, um padrão amplamente utilizado no mercado.

Ao final, teremos evoluído significativamente nosso Design System, avançado no Storybook, no NX e no Chromatic, e seremos capazes de publicar o projeto para todos verem e compartilharem com o time.

Pré-requisitos do curso

Para isso, é importante já ter familiaridade com Angular, NX e Storybook. Com essa base, será possível acompanhar o curso.

Não deixe de realizar as atividades ao longo do curso. Em caso de dúvidas, entre em contato com a comunidade da Alura. Já te esperamos no próximo vídeo, onde começaremos a implementar este projeto incrível.

Criando biblioteca input - Criando biblioteca com Nx Console

Nós já temos a base do nosso monorepositório e do nosso design system. Até o momento, criamos apenas uma biblioteca para o componente de botão e uma biblioteca para servir o storybook e todas as variantes daquele botão.

Estamos com o Figma aberto no navegador e podemos perceber que ainda há muitos componentes para serem implementados além do botão. Além do botão, temos as checkboxes, radio buttons, switch, campo de input e modal. Há um longo caminho pela frente.

Criando uma biblioteca

Para atender essa demanda da Alfabit, precisamos implementar mais alguns componentes. Podemos começar pelo componente de input. Vamos partir para a prática e criar uma biblioteca para esse componente de input. Vamos abrir o VS Code. Já estamos com o projeto configurado no computador. Deixamos uma atividade para que você faça isso também. Você pode clonar o projeto e instalar as dependências.

Como é mesmo o comando para gerar uma biblioteca no NX? Podemos abrir o terminal integrado. Vamos fechar o explorador lateral. O comando seria nx g. Precisamos saber qual é o plugin que tem o gerador de biblioteca. O plugin é o @nx/angular. Escrevemos dois pontos e o nome do gerador, que seria library.

nx g @nx/angular:library

Se não lembrarmos de cabeça, precisamos consultar a API para saber não só o nome do plugin e do gerador, mas também das opções que precisamos passar para o comando, como o diretório da biblioteca, se ela é publicável, o nome do NPM e outras opções. Esse processo pode ser um pouco trabalhoso.

A empresa do NX sabe disso e criou uma extensão para o VS Code que pode nos ajudar nesse processo, tornando-o mais fluido. Vamos mostrar essa extensão agora.

Vamos apagar o comando do terminal e pressionar "Ctrl + Shift + X" para abrir a aba de extensões do VS Code. Vamos pesquisar por "NX Console". Clicamos na primeira sugestão que aparece e, em seguida, no botão "Install" (instalar). Podemos conferir que essa extensão é da empresa NRWL e do site nx.dev.

Na barra lateral esquerda do VS Code, podemos clicar nos três pontos e encontrar a opção "NX Console". Clicamos nela e aparece uma nova barra lateral do NX Console. Vamos arrastar o ícone dessa extensão para a quarta posição para ficar mais organizado.

Fechamos a aba da extensão e mantemos a nova barra lateral. Ela tem três seções: uma de projetos, com os projetos do nosso monorepo, que inclui a aplicação "alfabit", a biblioteca "button" e a biblioteca "storybook.host". Vamos fechar a segunda seção, que não utilizaremos agora. A terceira seção é de Common NX Commands, que são os comandos comuns do NX, os mais utilizados.

A primeira sugestão dessa seção é um comando chamado "Generate (UI)". Podemos clicar nele. Ao clicar, aparece uma lista de todos os geradores de todos os plugins instalados nesse monorepo. Vamos pesquisar por "lib" e já aparece aquele gerador: @nx/angular, que é o plugin do qual ele faz parte, e o nome dele que é library. Há uma descrição dizendo que ele cria uma biblioteca Angular. Clicamos nessa opção e é nessa parte que o NX Console se destaca.

Fechamos a barra lateral e temos uma interface bem intuitiva para executar esse comando. As opções já vêm pré-definidas. Vamos definir essas opções para criar o componente de input. Podemos conferir o primeiro campo que se chama "name".

Há um ponto de interrogação que, ao passar o cursor por cima, diz que podemos fornecer um nome aninhado em vez de colocar a opção de diretório. Vamos fazer isso. No nome, escrevemos "libs/input". Conforme digitamos, o terminal abre automaticamente. Não é um bug, é um comportamento dessa extensão.

Conforme interagimos com a interface do NX Console, ele executa o comando com a opção --dry-run, apenas para prever qual seria a saída do terminal com a execução desse comando. Vamos conferir isso em breve.

Vamos deixar o terminal colapsado para não atrapalhar e vamos continuar preenchendo os campos da interface. Colocamos libs/input. Vamos descer um pouco mais. Podemos conferir as opções do lado esquerdo e clicar nas que queremos definir. Vamos clicar em publishable e marcar essa opção para deixar a biblioteca publicável ("Generate a publishable library"), caso queiramos publicar no NPM no futuro.

Vamos localizar a opção "importPath", onde definiremos o nome da biblioteca no NPM e o caminho de importação dentro do nosso monorepo. Colocamos @alfabit-alura/input, seguido do mesmo nome da organização que já criamos antes. Vamos localizar a próxima opção, que será "prefix". Nela, colocamos o prefixo "ab", o mesmo do botão que já definimos antes. Agora, na opção "selector", colocamos "ab-input".

Vamos subir o terminal para ver qual seria a saída desse comando sendo executado com o dry run. Vamos esperar um pouco. O NX está dizendo que geraria vários arquivos e pastas dentro de libs/input e todos os seus arquivos correspondentes.

Ele também atualizaria o "nx.json" e até o arquivo "extensions.json", além do "configbase.json". Está tudo certo. Vamos descer um pouco o terminal e clicar no botão superior direito, "Generate", para executar esse gerador de fato. Clicamos nele e, ao lado desse botão, há um botão para copiar o comando, caso queiramos compartilhar com colegas e mostrar como se gera uma biblioteca no NX.

O comando foi executado. Vamos fechar o terminal, abrir o Explorador de arquivos e conferir que a pasta "input" já foi gerada dentro da pasta "libs". Conseguimos gerar com sucesso uma biblioteca utilizando a extensão do NX Console. O próximo passo é começar a integrá-la com o storybook, mas isso será abordado no próximo vídeo.

Criando biblioteca input - Criando story com gerador

Nós já criamos nossa biblioteca para o componente de input utilizando a extensão do Nx Console. Já conseguimos visualizar essa biblioteca dentro do nosso monorepo. No entanto, ainda não estamos visualizando o componente de forma visual.

Para isso, utilizaremos o Storybook. Já temos uma biblioteca que disponibiliza o servidor do Storybook e precisamos colocar pelo menos um story do input dentro desse servidor.

Atualmente, se abrirmos a pasta "storybook-host > src > stories", temos um story para o componente de botão. Precisamos criar esse story do zero? É uma possibilidade. No entanto, o Nx também possui um gerador específico para criar um story para um componente já existente. Vamos usar novamente o Nx Console para executar esse gerador.

Abrimos a aba do Nx Console mais uma vez, clicamos no comando "Generate UI" da terceira seção. Digitamos o nome do gerador na caixa de texto da parte superior da interface, que será "stories". Ele faz parte do plugin @nx/angular, e o nome dele é stories. A descrição indica que ele cria arquivos de stories para todos os componentes declarados em um projeto. Selecionamos essa opção e fechamos a barra lateral.

Na interface visual, selecionamos o projeto para o qual queremos gerar os stories clicando no menu suspenso abaixo do campo "name". No caso, queremos gerar para o componente de input. Clicamos nele. O gerador faz parte do plugin do Angular e consegue gerar o arquivo de acordo com o componente existente. Dependendo dos @inputs dele, também consegue gerar os args necessários. Isso é interessante. Como o componente é recém-criado, o arquivo de story será simples.

Voltando à interface do Nx Console, desmarcamos a caixa do lado de "Set up Storybook interaction tests" no campo interactionTests, pois não trabalharemos com teste de interação agora.

Clicamos no botão "Generate" no canto superior direito. O terminal mostra que o arquivo "input.component.stories.ts" foi criado dentro da pasta do input. Fechamos o terminal, abrimos o Explorador, e vamos até a pasta "input > src > lib" e o arquivo de story foi criado junto com a biblioteca input ("input.components.stories.ts").

Já temos o esqueleto, a base de um arquivo de story, importando o meta, o InputComponent, fazendo o export default do meta, definindo o componente e um título para ele. Temos também o type Story na linha 9 e um story sendo exportado na linha 11, chamado Primary.

import type { Meta, StoryObj } from '@storybook/angular';
import { InputComponent } from './input.component';

const meta: Meta<InputComponent> = {
  component: InputComponent,
  title: 'InputComponent',
};

export default meta;

type Story = StoryObj<InputComponent>;

export const Primary: Story = {
  args: {},
};

Isso está correto. No entanto, estamos agrupando todos os stories na biblioteca "storybook-host". Para manter esse padrão, movemos o arquivo para a pasta "storybook-host > stories" clicando no arquivo e usando os atalhos "Ctrl + X" e depois "Ctrl + V".

Ajustamos a formatação do arquivo, adicionando alguns espaços. Precisamos ajustar na linha 2 o import do componente de input, que está com um caminho relativo ./input.

O VS Code perguntou se queríamos atualizar esse import. Dizemos que sim. Ainda está relativo, mas não queremos usar esse caminho. Fechamos a barra lateral para ter mais espaço. O erro indica que os projetos não podem ter um caminho relativo absoluto.

Devemos seguir o mesmo padrão usado no story do arquivo de botão. No arquivo de botão, usamos o import path @alfabit-alura/button. Faremos o mesmo no input. Removemos o caminho atual e digitamos @alfabit-alura/input, padronizando as importações do nosso monorepo. Salvamos o arquivo.

import type { Meta, StoryObj } from '@storybook/angular';
import { InputComponent } from './@alfabit-alura/input';

const meta: Meta<InputComponent> = {
  component: InputComponent,
  title: 'InputComponent',
};

export default meta;

type Story = StoryObj<InputComponent>;

export const Primary: Story = {
  args: {},
};

Posicionamos o arquivo no local correto. Agora, queremos ver se esse story aparece no servidor do Storybook. Podemos usar o Nx Console novamente. Abrimos a seção dele no VS Code. Para executar a tarefa Storybook do projeto "storybook-host", clicamos no nome do projeto na primeira seção, "storybook-host", e localizamos a tarefa "storybook".

Há um triângulo apontando para a direita, que é o botão de Execute Task (Executar Tarefa). Clicamos nesse botão. O terminal foi aberto e indica que executará o comando nx run storybook-host:storybook. É mais um comando que não precisamos lembrar de cabeça. Essa é a forma correta de executar a tarefa de um projeto. Podemos usar o Nx Console para ajudar e aumentar a produtividade ao trabalhar com o Nx.

Estamos aguardando a execução do comando. A construção do servidor demora um pouco, mas já voltamos. O servidor do Storybook foi construído, então voltamos ao navegador. Ele abriu automaticamente. Vemos o componente de botão que já existia, mas agora conseguimos localizar o "InputComponent" na raiz do Storybook. Damos um zoom para enxergar melhor.

Clicamos em "InputComponent" no menu lateral esquerdo e vemos que ele já tem uma Docs mostrando o input primário. Há apenas um parágrafo dizendo "Input Works", que é o código padrão da biblioteca Angular. Já está funcionando e exibindo o componente no Storybook.

No entanto, percebemos que ele foi posicionado separado do componente de botão. O componente de botão está dentro de uma seção chamada "src", uma parte "stories", mas o input está em outra seção. Vamos entender isso no próximo vídeo por que isso está acontecendo.

Sobre o curso Angular: evolua a documentação do seu Design System com Nx e Storybook

O curso Angular: evolua a documentação do seu Design System com Nx e Storybook possui 136 minutos de vídeos, em um total de 54 atividades. Gostou? Conheça nossos outros cursos de Angular em Front-end, ou leia nossos artigos de Front-end.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Criando biblioteca input
• Evoluindo Input e documentação
• Documentações com MDX
• Publicando Storybook com Chromatic
• Publicando com commits convencionais