Documentando interfaces com o storybook

Postado por: em 04/11/2021

O que é Storybook?

O storybook é um open source para criação de componentes UI de forma isolada, onde podemos documentar e testar componentes. Assim, quando um membro de equipe necessitar consultar o componente, será possível acessar as suas propriedades e variações, bem como entender como funciona o componente dentro da aplicação. 

Dessa forma, temos uma documentação organizada dos componentes dentro de determinadas aplicações, o que gera um ótimo recurso para o time, tanto para consultas como em testes de comportamento.

Como o storybook é um ambiente de desenvolvimento isolado, ele funciona como um “playground” para testar componentes. Nele, criamos arquivos de stories que recriam o componente com propriedades padrões, sendo possível fazer alterações dessas propriedades no próprio “playground” para validação de comportamento dos nossos componentes.

Resumindo: storybook é um open source com possível integração com vários frameworks front end como ReactVueAngular entre outros. Veja mais sobre storybook aqui.

O que é um Story?

Uma história é um estado do seu componente, que pode ter diversas propriedades, permitindo ao desenvolvedor escrever uma história para cada estado visualizando, assim, suas diversificações.

Um componente botão pode ter várias propriedades como disabled, color, size etc, essas são as diversificações que podemos aplicar nas nossas histórias. Ao longo do artigo, vamos ilustrar como isso é feito.

A imagem acima é uma história (story) de um botão.

Iniciando e instalando storybook em um projeto

Vamos criar nossa história em um projeto React, por exemplo:

  • Crie um projeto React com seguinte comando:

npx create-react-app storybook-demo

Assim, teremos nosso projeto iniciado. No momento, não vamos detalhar aqui sobre React, vamos focar no storybook.

  • Agora vamos instalar o storybook em nosso projeto:

npx sb init

Será criado uma pasta .storybook em nosso projeto. Nela, teremos os arquivos de inicialização main.js e preview.js.

  • No package.json crie um comando(script), caso não já tenha sido criado automático para rodar o servidor:

“storybook”: “start-storybook -p 6006 -s public”

  • Para rodar o servidor do storybook, rode o seguinte comando

npm run storybook

Ao abrir no navegador o link http://localhost:6006, veremos nosso playground do storybook, onde estarão nossas stories recém criadas.

Por padrão, dentro de src terá uma pasta chamada stories, que já vem com um story modelo. Por isso, vamos excluí-la (esta pasta src/story) e nos próximos passos criar um componente e seu respectivo story. Dessa forma, conseguimos assimilar melhor a criação e uso de fato.

Criando um componente de botão

Abaixo vamos criar o componente de Botão em src/components/button: 

Também criaremos os estilos em src/components/button (Utilizamos aqui styled-component): 

No no src/App.js vamos importar nosso componente de botão: 

Com nossa aplicação funcionando e nosso componente de botão já criado, já estamos prontos para criar nossa história.

Criando uma história

Vamos agora criar o story do nosso componente de botão. Em src/components/button, vamos criar um arquivo chamado index.stories.jsx.

Neste arquivo, podemos ver como é construído o story para que seja visualizado no nosso playground o padrão e suas variações. Agora, nosso componente está documentado e pronto.

Acessando storybook das nossas histórias 

Com nossa aplicação e histórias prontas, vamos rodar nosso servidor do storybook e acessar nossa documentação de componentes.

  • Rode o script storybook que criamos no início (“storybook”: “start-storybook -p 6006 -s public”)

yarn storybook

Após rodar o script acesse pelo navegador http://localhost:6006. Essa é a página que será aberta:

Podemos observar que o storybook consegue identificar todos os arquivos com extensão “.stories.jsx”, juntando todos nesse playground para vermos componente por componente. Se observamos o arquivo /.storybook/main.js, é possível notar que ele já possui a regra de mapeamento dos stories.

Clicando em cada variação do componente, podemos visualizar abaixo suas propriedades e testar mudanças nessas propriedades, acompanhando o comportamento do componente.

Na parte superior possui duas abas, “Canva”, que é a aba atual, e “Docs”, que está ao lado. Ao clicarmos na segunda, podemos ver tanto a variação principal quanto as demais variações de forma detalhada, bem como suas pré-visualizações e todas as propriedades listadas com seus respectivos tipos.

O quão útil pode ser no desenvolvimento do Front End

Com o storybook, temos uma facilidade enorme em compartilhar as informações dos componentes entre a equipe que está desenvolvendo o projeto. Quando um integrante for criar ou utilizar um componente, basta acessar o livro de histórias (storybook), identificar o componente em questão e rapidamente poderá entender como é a visualização dele e quais propriedades envolve seu comportamento no uso da aplicação.

Com um projeto onde seus componentes estão devidamente documentados, temos grande ganho de tempo para todos na equipe, favorecendo o ambiente também para futuros integrantes da equipe. Caso uma nova pessoa chegue na equipe posteriormente, ela poderá encontrar informações do projeto centralizadas e integradas.

Espero que tenham gostado do artigo! Acreditem, o storybook pode fazer muito mais com addons e actions. Vale a pena se aprofundar no assunto. 

O que é cultura ágil e por que ela é importante