NextJS: documentando seu Front-end com o Storybook

Documentando Front-ends - Apresentação

Olá, pessoas. Eu sou Mário Souto, e se você está me assistindo aqui é porque você está interessado em como aprender a melhorar documentação dos seus Front-Ends. E muito provavelmente você está curioso para ver essa ferramenta aqui: o Storybook, e é exatamente ela que eu vou te ensinar.

A minha ideia é ao longo dos próximos vídeos conseguirmos trazer para você um conteúdo que te ensine a fazer o Setup base dessa ferramenta e conseguirmos montar uma configuração nível Projeto open source, onde você consegue documentar os seus componentes, as pessoas podem interagir com as diferentes versões dele, podem abrir a documentação, ver cada uma das propriedades.

Muito do que é gerado automaticamente para tentar pular aquela dor que muita gente sente de ter que ficar escrevendo cada detalhe.

É exatamente essa a proposta que eu tenho de trazer para você aqui. E o legal do Storybook é que ele já é uma ferramenta muito rica, ele possui muitos plugins, nós vamos configurar bastante juntos, e eu te convido a se matricular neste curso e acompanhar os próximos vídeos aqui comigo.

Você vai conseguir fazer documentações pensando em projetos grande como, por exemplo: Material UI, pensando no Stacks, do Stack Overflow, enfim, tem várias referências que eu vou trazer aqui. Nós vamos usar o Storybook, mas você pode ir customizando para chegar nesse nível. Vamos aprender juntos?

Documentando Front-ends - Tour por referências de design systems

Antes de eu começarmos a falar sobre Storybook, partirmos para a prática e criarmos a nossa versão de uma documentação com código atualizável vamos dar um passo para trás. Gostaria de falar um pouco do porquê fazemos isso.

Se você olhar biblioteca de componentes populares como o Material UI e o Stacks, do Stack Overflow, é possível clicarmos em "Product" e ver todas as guide lines. que eles têm para montar os produtos. A ideia geral é tentar documentar padrões.

Por exemplo, eles têm claro como funciona para fazer os backgrounds, como fazem as bordas; até a nível de cor, quais são as cores que estão disponíveis para usar dentro do Stack Overflow.

Eles têm red, orange, yellow, green; todos esses valores comuns de cor até tamanhos de caixa em "Box Shadow". Tudo tem um nome. Seria: box shadow-sn, box shadow-md, box shadow lg, eles tentam dar nomes para tudo que tem valores abstratos. É muito mais fácil escrever "box shadow-sn" do que o código inteiro com todas as especificidades.

Além de documentar os componentes, usar o Storybook vai nos ajudar a deixar claro como os designers querem conversar com os desenvolvedores.

Você vai estar criando uma linguagem única para esses dois profissionais conseguirem trabalhar, o que é chamado de linguagem ubíqua. Além disso, isso facilita a integração da Code Base.

Por exemplo, peguei um exemplo de um layout que eu estou construindo. Temos uma imagem de fundo e o código. Mas se você for até a parte de "Tokens", que é um nome que damos para esses valores comuns, repare nos tons de cor que temos no projeto.

Quais são as cores primárias? É de 0 a 50 até 900, então pegamos por escala de cor, do mais claro ao mais escuro, e damos um nome. Então a cor principal do projeto é a cor primária. A cor secundária é cor accent.

Essas cores ganham nomes porque se amanhã quisermos mudar esse accent para azul, fica fácil de fazermos essa transição sem precisarmos mexer no código inteiro, você mexe em um ponto só, é o conceito de trabalhar com temas no Front-End.

Vamos abordar um pouco dessa parte de tema para fazermos a construção da nossa documentação, vamos documentá-la também, mas é importante passar essa parte didática.

E muitas coisas viram Tokens da empresa, por exemplo, os textos ou os ícones temos. Podemos ter um componente ícone, mas cada ícone que você tem na empresa é um Token, então é bom ter um lugar fácil para você conseguir visualizar tudo isso, ter clareza.

Um conjunto base de tokens nos ajuda a construir componentes, como por exemplo um botão, e com esse conjunto de é possível construir interfaces.

Então nós temos uma granularidade maior de como que nós organizamos tudo, mas isso nos ajuda a ter um pouco mais de consistência. Se quisessemos mudar toda a minha marca de verde para vermelho, seria possível.

É assim que algumas marcas grandes fazem para ter o mesmo site. Eu tenho certeza de que você já acessou algum e-commerce que que você pensou ser muito parecido com o de outra loja. É porque essas empresas grandes elas têm estratégias de fazer produtos White Label e todos os contextos que eu estou te passando aqui começam a se misturar.

Então toda a ideia de você trabalhar com tema; a ideia de você ter nomes que abstraem as coisas. Porque assim customizamos só o tokens de cada produto, então tal loja é vermelha, tal loja é azul, tal loja é verde, e a estrutura geral da página é a mesma, mas as cores mudam e assim muitas empresas conseguem escalar o desenvolvimento dos produtos.

Basicamente, o Storybook vai nos ajudar a fazer tudo isso, mas eu queria que você tivesse mais referências, então para encerrar este vídeo e você conseguir pegar um pouco mais de contexto dessa ideia que eu trouxe de white label, e de marcas com produtos diferentes, eu trouxe um exemplo.

O repositório do Github, que é o Awesome Design Systems, que basicamente é a ideia base desse princípio de documentar. Boa parte dos front-ends documentados estão rumando a ter um sistema de design.

Então é uma ter uma forma clara de você conseguir conversar entre desenvolvimento e design, e ter essa linguagem única para o pessoal conseguir trabalhar visualmente documentada e interativa, tal como o exemplo do "botão", que você consegue trocar os valores, com tudo pré-definido aqui. Do mesmo jeito que está lá no Figam, vai estar na code base aqui também.

Essa documentação varia de pessoa para pessoa, mas vocês podem olhar diferentes exemplos aqui: tem Blueprint e até da Nasa. O da Nasa foi descontinuado, mas você consegue ver como o pessoal da Nasa fazia para criar os componentes deles.

Tem o pessoal da Cloudflare, o Chakra UI, que é uma linha popular de Front-end também. Então é possível você ver vários exemplos.

Minha ideia inicial neste vídeo era trazer para você essas outras referências e garantir mais embasamento e a partir dessa base, no próximo vídeo, começamos com a parte prática. Escrevendo os códigos, criando o nosso Storybook do zero com um projeto pequeno, mas que vai trazer todos os conceitos que você precisa para criar documentações grandes na sua empresa.

Então nos vemos no próximo vídeo; mão na massa. Espero você lá.

Documentando Front-ends - Storybook: iniciando nosso setup

Chegou a hora de colocarmos a mão na massa! Vamos direto para VS Code. Tudo que eu fiz até agora foi criar um arquivo "README.md". Agora, começaremos o projeto.

Eu gosto de trabalhar bastante com o Next.js, então vou começar a criar um projeto nele e vou adicionar a configuração do Storybook.

Eu costumo usar o yarn para gerenciar o pacote, você pode usar o npm também,Vamos escrever o comando yarn init para começarmos o projeto de fato. Ele vai perguntar muitas coisas. Eu gosto de fazer o yarn init com o "-y" na frente, porque ele responde as coisas por padrão.

Então o primeiro passo vai ser o yarn init -y. Feito isso, eu vou criar uma página pages', nessa pasta o arquivo index.tsx, porque trabalharemos com o TypeScript. Todas as dicas que eu vou dar funcionam com para JavaScript também.

Eu estou fazendo com o TypeScript porque quando fazemos projetos maiores desse jeito, e o pessoal gosta de ter tipagem, então eu vou seguir na abordagem aqui. Mas pode ser uma preferência sua, eu vou dar dicas tanto para TypeScript quanto para JavaScript, fique à vontade.

Então eu vou fazer aqui um export default de uma function Homescreen() esta é a nossa tela inicial, onde eu faço o return de uma <div> com Home Page. E eu coloco "Home Page" dentro de <h1>.

Então eu comecei aqui com o nosso "home page" e tem alguns setups que eu vou fazer aqui que fica a seu critério fazer, por exemplo: eu gosto de padronizar os espaços para ficar com dois, clico com botão direito do mouse no meu VS Code, do lado esquerdo da tela, e vou gerar arquivo editorconfig, que é um arquivo base de configuração para arrumar os espaços.

Então ele gerado, eu boto "2" aqui, depois de indent_size = e coloco para sempre inserir uma linha no final dos arquivos, digitando "true" depois de insert_final_newline = que é algo o GitHub reclama. Para poder ter esse comando, você precisa ter a extensão no seu VS Code. '

Esse editorconfig é um padrão, então só de ter ele aqui, automaticamente o editor já ajusta os espaços para "2" aqui embaixo, e se eu formatar o documento ele deixa tudo correto.

Então nós já fizemos o setup inicial, criamos o arquivo inicial do Next e faltou ter os comandos para poder rodar. E o próprio Next aqui no projeto. Então eu vou fazer aqui: yarn add, que seria npm install, react react-dom next.

Por que eu estou fazendo todo esse setup? Se você vier comigo na documentação do Storybook, você vai conseguir ver que o próprio Storybook é feito para rodar num projeto que já existe, ele assume que você vai ter uma estrutura base de projeto ali para conseguir trabalhar.

Então se nós viermos na parte de instalação dele, ele tem o passo a passo, quais são os recursos. Eu vou clicar aqui no "Continue", esperar um pouquinho. O comando de init dele não é feito para projetos vazios, então estamos trabalhando em cima do formato padrão que você vai achar aqui na documentação.

Não quero fugir do padrão porque se você for fazer no futuro, você tem que conseguir fazer independente de versão, atualização e tudo mais. Então eu estou mostrando uma base, como está aqui.

Está demorando um pouquinho para instalar, eu vou aproveitar este momento para tomar um café, e o pessoal da edição vai colocar um corte para mostrar aqui a vocês.

Terminou a instalação. Então agora estamos com o next aqui no projeto de novo, configurado, eu vou criar aqui os scripts para que possamos rodar o projeto. Então eu vou ter aqui "scripts"; antes que eu seja incomodado aqui eu vou desabilitar o Copilot para ele não ficar sugerindo códigos e eu conseguir explicar com mais calma.

Vou rodar aqui o comando de start, então next start e junto com ele o next dev. E não pode esquecer também do build. Pronto, três comandos base do projeto Next.

Vou limpar aqui o meu terminal dentro do VS Code e vou rodar aqui o yarn dev. Como nós estamos usando o TypeScript, dentro desta pasta "Pages" eu preciso fazer essa instalação adicional aqui; então vou adicionar esses três extras aqui.

De novo mais uma instalação, vou deixar aqui, o pessoal da edição vai dar aquela cortada básica para vocês.

Instalação terminada. Então nós estamos com o projeto mais configurado agora, consigo rodar o nosso yarn dev para conseguirmos ver; ele gerou aqui um arquivo tsconfig.

Enquanto isso, eu vou vir aqui no meu browser e vou abrir aqui "localhost 3000". Pronto, estamos aqui com o nosso projeto base funcionando. Agora chegou a hora de começarmos a adicionar o setup do Storybook.

Só um ponto antes que eu queria fazer aqui para mostrar a vocês: quando eu rodei aqui o projeto, repara que ele está detectando 3000 arquivos aqui. Então é importante eu colocar o gitignore deste projeto.

Então eu vou rodar npx gitinore node só para ele gerar um arquivo aqui para mim, que vai ignorar a pasta "node_modules" e algumas outras coisas que eu não quero comitar do meu projeto.

E então se eu der um refresh aqui, na lateral esquerda superior da tela, são só 8 arquivos que temos até agora, que eu já vou fazer um commit, colocando aqui o A1.3 para deixar separado aqui.

[06:23]: Então eu vou dar um commit nesta parte base e vou publicar essa branch que fizemos aqui. Agora, sim, eu faço a parte do Storybook. Então eu vou, basicamente, copiar o comando que eles têm aqui na documentação: npx storybook init.

[06:47]: Neste exato momento, se a gente for lendo aqui com calma, ele fala que é o jeito mais simples de colocar Storybook no projeto, ele está adicionando suporte para a nossa aplicação com React, que ele identificou aqui.

Enquanto ele instala, vamos adicionar uma configuração dentro aqui do "tscongif", que veio errado, ele está com um vermelho, faltou preencher antes a configuração "moduleResolution", e esse "moduleResolution" eu vou colocar como "node". Agora ele parou de ficar vermelho, podemos fechar agora.

O setup está teminado e finalmente terminamos a configuração, agora podemos rodar o comando do Storybook, que é adicionado.

Após rodar o último comando feito, repare que foram criados novos 23 arquivos, não se assustem com essa quantidade, tudo que foi criado estrá na pasta "Stories", que exploraremos ao longo dos próximos vídeos, criaremos nossas próprias histórias. Storybook vem de "histórias", que é como você conta como os seus componentes são configurados, como eles são documentados.

Para vermos o resultado do que fizemos agora, eu vou rodar aqui yarn storybook, então uma vez que eu rodo este comando ele vai começar a carregar toda a configuração que precisa para conseguir rodar com o nosso projeto, vai fazer aquele setup inicial e vai abrir aqui o localhost.

Eu vou ajustar aqui para que ele abra dentro do meu navegador do Chrome. Nós já temos uma documentação inicial aqui, ela tem bastante coisa. Repare que ela tem um botão, tem algumas configurações aqui, dá até para mudar a cor; mas o ponto é o seguinte: isto tudo já está pronto. A ideia é você entender como isso é feito, como construímos o nosso. Mas só nos próximos vídeos começaremos a fazer essa parte mais específica.

Lembrando que até o final veremos como colocar no ar, o deploy, como colocar no ar este projeto, o comando de build, qual é a estratégia que precisamos seguir, enfim. Tem muito conteúdo legal, então eu vejo você no próximo vídeo para explorarmos mais essa parte de Stories aqui e começarmos a ter nossas próprias histórias no Storybook.

Até o próximo vídeo, tchau.

Sobre o curso NextJS: documentando seu Front-end com o Storybook

O curso NextJS: documentando seu Front-end com o Storybook possui 88 minutos de vídeos, em um total de 36 atividades. Gostou? Conheça nossos outros cursos de Next.JS 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:

• Documentando Front-ends
• Recursos do Storybook com React
• Temas e Providers
• Customizando o Storybook
• Deploy e dicas finais