Docz vs Storybook

Hoje vamos avaliar duas libs feitas para documentação: Storybook e Docz.

O Storybook é uma lib que tem sido utilizada para fazer documentação de componentes, tendo o foco em ser um ambiente de desenvolvimento para UI components e testes, podendo ser configurada para dar log nos event handlers como onClick e onChange.

O Docz é uma lib criado por um brasileiro que vem com a proposta de realizar documentações com ZERO configuração. Ela é uma lib que utiliza MDX para exibir os componentes em meio ao markdown.

Para essa análise, estarei utilizando o Storybook na versão 3.4.10 e o Docz na 0.10.2.

Docz

Instalação

Em um projeto, adicione o Docz como uma dev-dependency.

yarn add docz --dev

Desenvolvimento

Para executar o projeto no modo de desenvolvimento, basta rodar yarn docz dev.

Em seguida, crie dois arquivos, um será o seu componente React, como por exemplo Avatar.js, e o outro será um arquivo .mdx com o nome que você desejar, eu costumo manter o mesmo nome do componente que será usado.

Uma das coisas legais que eu vi no Docz é não precisar configurar nada. De início pensei que os arquivos .mdx teriam que ficar na mesma pasta que os componentes, jogados lá criando uma bagunça, mas não é o caso. Se eu quiser posso criar uma pasta para organizar os meus .mdx e não precisarei configurar a localização dos arquivos em lugar nenhum. O Docz é uma ferramente inteligente que consegue localizar os arquivos e montar sua documentação sozinho, sem que o programador tenha que bater a cabeça.

Fonte de exemplo:

---
name: Avatar
route: /
---
import Avatar from '../components/Avatar'
import { Playground, PropsTable } from 'docz'
# Avatar
## Properties
<PropsTable of={ Avatar } />
## Demo
<Playground>
    <Avatar>W</Avatar>
</Playground>

Storybook

Instalação

Assim como o Create React App, o Storybook possui um CLI para ser usado no terminal para configura-lo no seu projeto. Instale utilizando o comando abaixo:

npm i -g @storybook/cli

Após instalado, você deve configurar o Storybook no seu projeto com o comando:

getstorybook

Configuração e Desenvolvimento

Após instalar o Storybook, é possível observar que duas pastas foram criadas, uma é a ./.storybook que contém arquivos de configuração, e a outra pasta é a ./stories, que seria responsável por agrupar as stories, que é um estado único do seu componente, algo como um caso de teste visual.

Para rodar o Storybook, basta executar yarn storybook para iniciar o desenvolvimento. Feito isso, é só ir para a url exibida no log do seu terminal.

Por padrão, o projeto já vem configurado com um componente Button de exemplo, e sua definição fica no arquivo ./stories/index.js.

Para adicionar stories você precisa utilizar o seguinte trecho no seu arquivo ./stories/index.js:

storiesOf('Nome no menu lateral', module)
    .add('Nome do subitem no menu', () => <MyComponent />)

Para adicionar vários “subitens” e variações do seu componente, apenas encadeie quantos .add(...) forem necessários.

“Mas Lari, eu vou ter de colocar todas as minhas stories nesse único arquivo?”

Nos meus testes, a configuração padrão do Storybook só pegou as stories que estavam no ./stories/index.js, e para poder quebrar em vários arquivos tive de mexer nas configurações. Para carregar dinamicamente suas stories, teremos de alterar o arquivo ./.storybook/config.js, lá você pode definir uma regex para pegar todos os arquivos que você quiser. No exemplo dado na documentação (exemplo abaixo), a regex pega todos os arquivos em que o nome termina com .stories.js e os utiliza para gerar as telas:

import { configure } from  '@storybook/react';
const req = require.context('../src/components', true, /\.stories\.js$/)
function  loadStories() {
    req.keys().forEach((filename) =>  req(filename))
}
configure(loadStories, module)

Agora você já pode deletar a pasta ./stories criada pela biblioteca e criar quantos arquivos quiser desde que tenha .stories.js no final. No meu caso, eu preferi deixar dentro da pasta ./stories e alterei a regex pra pegar todos os arquivos dentro da pasta, deixando a minha variável req assim:

const req = require.context('../src/stories', true, /^\.\//)

Avaliação

Avaliando os dois projetos, pude perceber que se pode fazer a mesma coisa com ambos, mas cada um tem uma proposta diferente.

A função Docz é documentar componentes e que de quebra você pode interagir com eles através do editor de código que o <Playground /> disponibiliza. Para mim, essa edição de código em tempo real (adicionada na versão 0.10.0) e a funcionalidade<PropsTable /> são muito úteis. Vejo que o Docz auxilia na fase de desenvolvimento do componente por você poder mockar os dados e fazer um live edit e principalmente na fase de documentação, podendo fazer essas duas fases juntas.

Já o Storybook é para testes visuais como exibição dos componentes e visualização dos event handlersde interação no console na parte inferior da tela desde que você o tenha configurado para tal, auxiliando na fase de desenvolvimento dos componentes.

Tendo isto em vista, não há nenhum problema em usar os dois projetos ao mesmo tempo, pois cada um faz algo diferente, mas se viessem me perguntar qual deles eu usaria, as respostas seriam as seguintes:

• Preciso fazer documentação: Docz
• Estou desenvolvendo componentes: O que mais lhe agradar. Docz tem alteração de código em tempo real, mas com o Storybook você pode ver os logs dos event handlers (onClick, onChange…)
• Estou apenas documentando: Docz
• Irei apresentar meus componentes para outras pessoas: Docz
• Preciso testar o que o meu onClick me retorna: Storybook
• There’s no time to explain, jump in the project: Docz
• Mas eu gosto do Storybook/Docz: Faça o que o seu coração mandar

O Storybook possui alguns plugins que podem se acoplados, e se você tiver tempo você pode experimentar o Storybook, mas a facilidade de usar o Docz é incrivelmente grande, apenas uma rápida leitura na doc já me foi suficiente para utiliza-lo, enquanto o Storybook me demandou um tempinho. Um ponto negativo do Storybook é que ele poderia já vir configurado para pegar todos os arquivos da pasta ./stories.

Hoje a minha escolha é utilizar apenas Docz para fazer a documentação.

E você? O que escolheria?

Dúvidas, sugestões e comentários são super bem-vindos! E comente abaixo caso eu tenha esquecido de alguma coisa.

Fontes:
Docz
Conhecendo o Docz
Criando componentes com Storybook
Storybook