Strapi

O que é

O Strapi é um headless CMS open source que conta com diversas opções que permitem personalizar e construir a estrutura e o conteúdo de um site. Para isso, o Strapi disponibiliza uma interface feita em React onde é possível então, criar a estrutura desejada para manipular os dados.

Instalação

Para criar um projeto novo no Strapi, basta seguir o passo a passo abaixo:

  1. No terminal, executar o seguinte comando:
# Com yarn
yarn create strapi-app my-project

# Com npm
npx create-strapi-app my-project
  1. Selecione um tipo de instalação:
  • Quickstart (recommended), utiliza o banco de dados padrão (SQLite)
  • Custom (manual settings), permite você escolher o banco de dados da sua preferência

  1. Quando o terminal perguntar Would you like to use a template?, digite y caso queira usar um template pré-definido ou digite n caso contrário.

  2. (Template) Entre as opções disponíveis, selecione o template que desejar.

  3. (Instalação customizada) Entre as opções de banco de dados disponíveis, selecione a que desejar

  4. (Instalação customizada) Dê um nome para o banco de dados do seu projeto

  5. Concluída a instação, basta executar o comando yarn develop ou npm run develop

Como usar

O Strapi possui uma interface gráfica que é capaz de interagir com os dados armazenados no banco de dados definido na instalação. Para facilitar a organização e melhorar a experiência do usuário, o Strapi divide os dados em basicamente dois grupos grandes: Single Type e Collection Type.

Single Type

Esta estrutura caracteriza uma coleção de dados que não tende a ser repetida mais de uma vez. Como o próprio nome sugere, o Single Type é um tipo único, ideal para a criação de páginas em um site, por exemplo, onde cada página tende a ter uma estrutura própria que não será a mesma de outra página.

Collection Type

Já a Collection Type, serve justamente para ser utilizada quando temos uma estrutura única que tende a ser repetida diversas vezes com dados diferentes. Ela é equivalente a uma tabela no banco de dados, que pode conter diversas entradas sempre respeitando a estrutura definida.

Tipos de dados

Ao definir uma nova estrutura (seja ela Single ou Collection), devemos escolher quais os campos irão compor tal estrutura. O Strapi disponibiliza diversos tipos de campos, como string, número, data, texto rico, imagem, entre outros. Basta escolher aqueles que desejar e não esquecer de salvar após concluir

Dados especiais

Além dos tipos de dados convencionais citados anteriormente, existem dois tipos especiais que merecem uma atenção maior

  • Componente - o componente é uma estrutura que pode ser comparada com um objeto no JavaScript. Nele, podemos agrupar um conjunto de dados que pode ser reaproveitável em diferentes Collections ou Single Types. É muito bom utilizá-lo quando temos uma estrutura que se repete em diversos lugares e, também, quando precisamos aninhar certos dados.

  • Dynamic Zone (DZ) - como o próprio nome sugere, através deste tipo podemos criar uma zona de dados dinâmica. Em outras palavras, a DZ é sempre utilizada quando precisamos "fugir" de uma estrutura fixa, dando maior liberdade para o usuário na hora de criar o conteúdo de alguma página. A DZ é sempre composta por uma quantidade finita de componentes. Por exemplo, vamos supor que tenhamos uma Collection com o nome Blog que é composta por dois campos, um de richtext e outro de imagem. Quando formos cadastar um Blog novo, ficamos restritos a sempre utilizar apenas um richtext e uma imagem, deixando muito restrita a criação de conteúdo. Para contornar isso, podemos criar dois componentes: o primeiro possui o nome Content e apenas um campo de richtext e o segundo possui o nome Image e apenas um campo de imagem. Agora, criamos um campo de Dynamic Zone dentro do Blog e colocamos os dois componentes criados nesta DZ. Assim, quando o usuário cadastrar um novo Blog, ele poderá escolher quais componentes deseja usar (Content ou Image) e quantas vezes quiser. Sendo assim, a DZ funciona como um array. Podemos chamar ela várias vezes sempre escolhendo algum dos componentes inseridos nela. No caso do exemplo anterior, poderíamos, então, cadastrar um Blog da seguinte maneira: [Content, Image, Image, Content, Image, Content]. As opções são inúmeras, o que garante uma boa liberdade para o usuário.

Plugins

Através dos plugins, o Strapi permite utilizar outros serviços de uma maneira prática e fácil. Entre eles, podemos destacar três: Internationalization (i18n), Email e GraphQL.

Internationalization (i18n)

Este plugin permite que tenhamos conteúdos em diferentes idiomas no nosso projeto de uma maneira fácil e organizada. Quando este plugin está instalado e criamos uma nova Collection ou Single Type, podemos marcar a opção de utilizar a internacionalização. Quando ativada, automaticamente é inserido no banco de dados um campo locale que informa a localização do conteúdo criado. Além disso, também podemos habilitar ou não a internacionalização para cada campo dentro de uma coleção. Assim, os campos que estiveram com a i18n habilitada, terão seu conteúdo específico para cada localização. Caso desativada, o campo terá o mesmo conteúdo para todas localizações.

Para configurar os idiomas do projeto, basta acessar o painel de admin do Strapi nas configurações e depois na seção de internacionalização. A documentação completa deste plugin encontra-se aqui.

Email

O plugin de email nos permite automatizar o envio de email quando determinada ação acontece no Strapi. Além do serviço padrão, é possível instalar outros serviços alternativos de acordo com a sua necessidade. A documentação oficial conta com mais detalhes e apresenta alguns exemplos de como utilizar este serviço.

GraphQL

O GraphQL é um excelente plugin caso o usuário não queira consultar os dados do Strapi através de requisições convencionais. Seu uso é simples e basta apenas instalar o plugin que tudo já é configurado automaticamente. Depois de instalado, na rota /graphql encontra-se o playground do GraphQL, onde podemos criar e testar novas queries e mutations assim como consultar a documentação da API.

Além disso, o Strapi também permite a criação de queries e mutations customizadas caso o usuário precise. A documentação completa deste plugin encontra-se aqui

Sistema de diretórios e arquivos

Quando criamos um projeto com o Strapi, temos acesso às pastas e arquivos criados. O Strapi utiliza um sistema de diretórios e arquivos que permite o usuário manipular as informações via código. Temos acesso e permissão para acessar praticamente tudo. Coleção de dados, plugins, banco de dados, entre outras funcionalidades, possuem customização através do código. Todas as informações a respeito da estrutura do projeto podem ser vistas aqui

Coleções de dados

Todas informações de uma coleção de dados se encontram dentro da pasta /api. Toda vez que uma Collection ou Single Type é criada no painel, automaticamente é criada uma pasta em /api/**. Dentro desta pasta, todas as informações da estrutura em questão podem ser consultadas, que são organizadas da seguinte maneira:

  • /api/**/config/routes.json: este arquivo armazena todas as rotas existentes dentro da collection. Por padrão, já existem algumas rotas predefinidas que permitem o usuário buscar os dados cadastrados na collection, cadastrar um novo dado, atualizar um dado existente, etc. Além disso, é possível, também, definir novas rotas como também utilizar queries que o próprio Strapi disponibiliza para facilitar o manuseio de rotas predefinidas.
  • /api/**/models/**.settings.json: este arquivo é responsável por armazenar o schema da coleção. Além do painel de admin, também é possível manipular os campos através deste arquivo.
  • /api/**/controllers/**.js e /api/**/services/**.js: estes dois arquivos costumam ser utilizados para definir algum script ou ação. Por exemplo, quando o usuário insere um novo dado em uma determinada Collection, queremos que um email seja enviado para este usuário. Podemos então, criar o código para isso nesses arquivos. Tarefas como automatizar a inserção de dados no projeto ou manipular os dados no geral, também podem ser feitas aqui.

Mais informações, especialmente sobre o back-end do Strapi, podem ser consultadas neste link.

Plugins

As configurações de plugins são feitas na pasta /extensions. Para mais detalhes, consultar este link

Problemas recorrentes e limitações do Strapi

No geral, o Strapi é um excelente CMS e possui poucos problemas. Porém, é importante destacar alguns deles e também algumas limitações que não estão tão claras na documentação para quem está começando a utilizar a ferramenta.

  1. Dados aninhados - quando estamos definindo uma estrutura nova no Strapi utilizando componentes, precisamos muitas vezes definir um componente dentro de outro, o que acaba gerando um aninhamento dos dados. Pelo painel de admin, não podemos ter mais do que 2 níveis de aninhamento. A estrutura exemplificada logo abaixo, é um caso onde temos 3 níveis de aninhamento o que não é permitido no Strapi. Para contornar isso e conseguir criar uma estrutura semelhante, é preciso acessar o arquivo com o schema da coleção e definir manualmente. Apesar de ser uma solução útil e funcional, ela não é recomendada pelo Strapi de acordo com este post.
objeto {
  campo1
  campo2

  objeto2 {
    campo1
    campo2

    objeto3 {
      campo1
      campo2
    }
  }
}

  1. Erros ao alterar a estrutura de alguma Collection ou Single Type - ao tentar inserir ou remover algum campo em um projeto já estruturado com uma quantidade considerável de dados, podemos nos deparar com alguma mensagem de erro que o painel do Strapi nos informa quando apertamos em Salvar. Quando isso acontecer, devemos sempre conferir o terminal que está rodando o projeto. Muitas vezes, quando um erro é informado no painel mas não no terminal, é provável que nenhum erro de fato tenha ocorrido. Priorize sempre os logs do terminal para ter certeza. Se a aplicação reiniciar normalmente após salvar é porque deu tudo certo. Em caso de realmente ter ocorrido um erro, tente manipular a estrutura do projeto direto no código mas tenha cuidado para não remover ou editar algo que não deva.

  2. Limite de requisições no GraphQL - por padrão, o GraphQL permite buscar um número máximo de 100 itens por requisição. Caso você tenha um volume de dados muito grande que precise consultar e não esteja recebendo tudo, é bem provável que seja por causa disso. Para aumentar o limite padrão, basta acessar este link e seguir a documentação.

  3. Requisições proíbidas no GraphQL - sempre que uma nova Collection ou Single Type for criada, é preciso autorizá-la nas configurações do Strapi. Caso isso não seja feito, ao tentar fazer uma requisição para a coleção em questão, o usuário receberá uma mensagem informando que a rota está com o acesso proibido.

← Visual Studio Code