Por que você deveria usar o Electric

Um overview sobre o Electric e como ele irá lhe ajudar a criar documentações de forma rápida e eficiente.

Não! Não é só mais um framework frontend. Electric é um poderoso gerador estático criado especificamente para que seus projetos não tenham apenas um README.md ou um JSDoc configurado, e sim uma documentação extremamente detalhada e acessível.

*O intuito deste post não é mostrar muito código, mas nos apresentar o que é o Electric, para que serve e como utiliza-lo nos nossos projetos.

Mas afinal, para que servem geradores estáticos?

Falando de forma resumida, basicamente, geradores estáticos criam sites sem conexão com banco de dados ou alguma linguagem de backend configurada, suas pastas apenas irão conter arquivos .html, .css, .js e imagens. Tudo isto a através de arquivos de configuração, na maioria dos casos, arquivos markdown (arquivos com extensão .md). A ideia de geradores estáticos já existe há um bom tempo na comunidade frontend, mas veio se tornando mais forte cerca de 3 anos atrás, com a adoção dos blogs estáticos, onde muito dos desenvolvedores frontends começaram a utilizar geradores para criarem seus blogs.

Mas por que o Electric?

Diferente dos geradores estáticos que encontramos no Github, Electric não foi desenvolvido exclusivamente para criar sites ou blogs estáticos, apesar de você também conseguir utilizá-lo para tal feito.

Como mencionado no inicio do artigo, ele foi feito inicialmente para que você possa desenvolver de forma rápida e acessível suas documentações. Umas das features que podem nos chamar mais atenção, é o tema padrão que o Electric nos possibilita e uma documentação com um modelo incrível, que já vem integrada com uma busca instantânea utilizando o recurso de auto-complete.

Para conhecer algumas dessas features, nada melhor que compararmos com o visual do Docusaurus, um gerador estático do Facebook utilizado para criar a documentação do React Native, Jest e do Graphql.

Docusaurus

Começaremos dando uma olhada na seção mais importante do seu projeto: documentação.

Assim como o Docusaurus, o Electric nos fornece uma busca instantânea, a diferença que em cada página temos tópicos fixos flutuantes ao lado direito, relativos a página em que o usuário se encontra, além do layout ser visualmente mais clean e agradável.

Abaixo podemos ver alguns gifs de comparação da seção de documentação do WeDeploy (feito em electric) e do Docusaurus:

Página de documentação do Docusaurus

Seção de documentação do WeDeploy

O Electric também nos possibilita um tema padrão já integrado, bastante clean e agradável, como podemos ver no site do MetalJS e SennaJS:

Site do MetalJS feito em Electric

Site do SennaJS

Note que o mesmo tema é muito flexível para customização, mas eu pessoalmente acho que o tema inicial já é tão legal que você não irá precisar modificá-lo.

Abaixo a página do All Animation CSS3 que está sendo construída, seguindo o tema inicial do Electric:

As únicas informações mudadas, foram o nome do site e descrição.

Com um tema incrível, e uma documentação da hora, o Electric também nos oferece uma página de updates e um blog muito legal.

O Electric já vem com o MetalJs (framework de componentes similar ao react, que utiliza o incremental DOM ao invés do virtual DOM) integrado, porém você é livre para utilizar qualquer tipo de framework da sua preferência.

Instalando e utilizando o Electric

Para utilizar o Electric é muito simples, basta instalar ele através do npm ou yarn:

instalando através do npm:

npm i -g electric-cli

instalando através do yarn:

yarn global add electric-cli

Após instalar global podemos iniciar o projeto utilizando o comando:

electric init

O qual irá lhe solicitar um nome de projeto, de pasta, repositorio de github e Google Analytics tracking ID, como podemos ver na figura abaixo.

Ilustração do electric-cli

Você pode saber mais sobre o electric.config.js na documentação oficial do electric.

A imagem ao lado demostra a estrutura de projeto que será criada no seu diretório atual, após você informar os dados solicitado pelo electric-cli.

Note que na raiz do seu projeto temos um arquivo chamado electric.config.js, este arquivo fornece as opções de configurações para o electric.

Para visualizarmos nosso site estático rodando no browser, basta digitar o seguinte comando na raiz do seu projeto:

electric run

Após isto, um servidor local NodeJS será criado e você poderá visualizar seu novo projeto através da url: http://localhost:8888.

Caso você queira mudar a porta do seu servidor local, basta digitar o seguinte comando em seu terminal:

electric run -p 3000

O Electric segue o conceito de layout e páginas, onde os layouts são definidos através de arquivos no formato .soy (linguagem de template que o Google utiliza e da suporte) e as páginas são definidas pelos arquivos markdown (.md).

Em um futuro breve, veremos de forma mais técnica (Rock and code \o/) como podemos customizar o electric e criar algumas seções e componentes customizados.

Um abraço, e até a próxima 😃