Skip to content

Estrutura do front end

AldemirLucas edited this page Oct 26, 2026 · 2 revisions

Estrutura do front-end

Onde fica cada coisa dentro de next/ e as convenções que o código segue hoje. Para a visão geral (renderização, autenticação, integrações), veja Arquitetura.

Componentes (components/)

Os componentes seguem o atomic design. Na prática, a divisão é por tamanho e por quanto o componente sabe do domínio:

Pasta O que vai aqui Exemplos
atoms/ Peças pequenas e genéricas, quase sempre um wrapper de um componente do Chakra com estilo fixo Button, Link, Toggle, Checkbox, ReadMore, Text/
molecules/ Blocos compostos por átomos, ainda reaproveitáveis em várias páginas Menu, Footer, Banner, Tour, PhoneInput, TableColumns
organisms/ Seções inteiras de uma página, com estado e busca de dados TablePage, DatasetResource, PaymentSystem, DatasetSearchCard
templates/ O "esqueleto" das páginas main.js, 404.js, 500.js

Átomos que valem conhecer

  • atoms/Text/: a tipografia do site. Display, TitleText, LabelText e BodyText aplicam fonte, tamanho e altura de linha por uma prop typography (small, medium, large). Use esses em vez de <Text> com fontSize solto.
  • atoms/Link.js: envolve o next/link, mantém o locale atual e, se o href começar com http:// ou https://, abre em nova aba.
  • atoms/Button.js, Toggle.js, Checkbox.js: os controles com o visual da BD.

Organismos

Os organismos maiores ficam soltos em organisms/. Os que pertencem a uma única página ou funcionalidade ficam em subpastas:

Subpasta Usada por
organisms/home/ pages/index.js (Hero, TablesStats, BePartner…)
organisms/blog/ pages/blog/index.js e pages/blog/[slug].js (Home, Slug)
organisms/componentsUserPage/ pages/user/index.js: cada aba da página de usuário (Account, PlansAndPayment, BigQuery…)
organisms/chatbot/ pages/chatbot.js. Veja Chatbot

TablePage, RawDataSourcesPage, InformationRequestPage e ResearchPaperPage são as abas de recurso da página de dataset, escolhidas por DatasetResource.

Templates

Quase toda página é embrulhada em MainPageTemplate (templates/main.js), que monta Menu + conteúdo + Footer:

import { MainPageTemplate } from "../components/templates/main";

<MainPageTemplate paddingX="24px" userTemplate>
  ...
</MainPageTemplate>

Props úteis: cleanTemplate (menu simplificado e sem rodapé), userTemplate (menu da área do usuário e sem rodapé), footerTemplate e backgroundColor. As exceções são pages/chatbot.js, que tem layout próprio, e pages/user/[username].js, que só redireciona para /user. templates/404.js e 500.js são usados por pages/404.js e pages/500.js.

Páginas (pages/)

Uma rota por arquivo, no pages router do Next 12. As rotas de API em pages/api/ estão em Rotas da API Next.

Área Arquivos
Home e institucional index.js, about-us.js, transparency.js, invited-researchers.js, terms.js
Dados search.js, dataset/[dataset].js
Produtos e vendas prices.js, bdpro.js, services.js, chatbot-lp.js, contact.js, contact-consulting.js, bd-orgs.js
Conteúdo blog/index.js, blog/[slug].js, docs/[slug].js, faq.js, case-studies/index.js, case-studies/[id].js
Usuário user/index.js, user/login.js, user/register.js, user/activate-account.js, user/check-email.js, user/password-recovery.js, user/survey.js, user/[username].js
Chatbot chatbot.js
Erros e app 404.js, 500.js, _app.js

_app.js registra o ChakraProvider, o QueryClientProvider, o appWithTranslation, as meta tags padrão por idioma e o GTM. Não há _document.js.

hooks/

Hook Para que serve
pages.hook.js → withPages() Devolve { props: {}, revalidate: 30 } para o getStaticProps. Apesar do nome, não é hook React
useCheckMobile.hook.js useCheckMobile() e isMobileMod(), para layout mobile
useCheckoutCampaign.hook.js Guarda a intenção de checkout vinda da URL (chamado em _app.js)
useABTestVariant.js Sorteia e persiste a variante de um teste A/B (usado em dataset/[dataset].js)
useChatbot.js, useThreads.js, useChatbotAuth.js Estado e chamadas do chatbot. Veja Chatbot
useFitToContent.js, useMinDuration.js, useIsomorphicLayoutEffect.js Utilitários de UI usados pelo chatbot

context/, lib/, middlewares/ e constants/

  • context/ChatbotContext.js: provider usado só pela página do chatbot.
  • lib/: código só de servidor: authCookie.js (cookie token) e requireChatbotAuth.js. Detalhes em Arquitetura.
  • middlewares/: authUser.js e _middleware.js não são importados por nenhum arquivo. _middleware.js também não roda como middleware do Next, que só procura esse arquivo dentro de pages/.
  • constants/stripePlans.js: seleção de planos do Stripe. Veja Stripe.

Conteúdo estático (content/ e blog/)

Markdown com front matter (lido com gray-matter), um diretório por idioma. Quem lê os arquivos são funções em pages/api/, chamadas no getStaticProps.

Pasta Formato Lido por Página
content/docs/{pt,en,es}/ .md → MDX (next-mdx-remote) pages/api/docs docs/[slug].js
content/FAQ/{pt,en,es}/ .md com question, categories, keywords, id getAllFAQs em pages/api/faqs faq.js
content/bdPro/FAQ/, content/services/FAQ/, content/chatbot/FAQ/ Mesmo formato do FAQ getAllFAQs(locale, "<pasta>/FAQ") bdpro.js, services.js, chatbot-lp.js
content/userGuide/{pt,en,es}/ .md → MDX, um por dataset (br-ibge-censo-2022.md…) pages/api/datasets/getUserGuide dataset/[dataset].js
content/caseStudies/{pt,en,es}/ .md pages/api/caseStudies case-studies/*
content/termsOfService.js, privacyPolicy.js Componentes React Import direto terms.js
blog/{pt,en,es}/ .md → MDX, nome do arquivo = slug pages/api/blog blog/*

Para criar um post, adicione blog/<idioma>/<filename>.md (o mesmo filename nos três idiomas) e coloque as imagens em public/blog/<filename>/. O front matter tem title, description, date.created, authors, thumbnail, categories, published e, opcionalmente, slug para a URL naquele idioma. Detalhes em Conteúdo editorial.

public/

Pasta O que tem
locales/{pt,en,es}/ Traduções, um JSON por namespace (common, menu, dataset, user, chatbot…)
img/ Imagens e logos. img/icons/ tem quase só ícones como componentes JS (createIcon do Chakra), importados direto de public/
blog/<slug>/ Imagens dos posts
docs/ Imagens e GIFs da documentação
raiz favicon_default.ico (pt/es), favicon_en.ico (en), robots.txt

Estilos (styles/)

  • Chakra UI v1: o ChakraProvider usa o tema padrão. Não existe extendTheme, então cores, fontes e espaçamentos são passados como props em cada componente (ex.: color="#2B8C4D"). Para manter a consistência, prefira os átomos de Text/ e Button.
  • globals.css: importado em _app.js. Carrega as fontes do Google (Ubuntu, Lato, Roboto) e estiliza o que o Chakra não alcança: paginação (react-paginate), checkbox do Chakra, scrollbar e elementos do blog.
  • CSS modules (*.module.css): para casos pontuais, como paymentSystem, imgCrop, toggle, faq e bdpro.

utils.js

Funções compartilhadas, sem organização por domínio. Os grupos principais:

  • Domínio e idioma: getDomain, isBasedosdadosDomain, getDiscordUrl, localizeQueryTableAlias.
  • Usuário e sessão: getUserFromCookie, clearClientSession, isUserLoggedIn, getUserPageHref.
  • Assinaturas: hasBDProSubscription, hasChatbotSubscription, getSubscriptionType, fetchChatbotPlan.
  • Campanha de checkout: persistCheckoutCampaign, resolveCheckoutCampaign, redirectToChatbotCheckout…
  • Telefone: formatPhoneInput, normalizePhone, isValidE164Phone…
  • Diversos: triggerGAEvent, formatBytes, formatMetaDescription, cleanGraphQLResponse.

Convenções observadas

  • Nomes de arquivo: componentes em PascalCase.js. Hooks em camelCase com prefixo use, alguns com o sufixo .hook.js (os mais antigos). Não há TypeScript.
  • Exportação: a maioria usa export default, mas vários átomos e moléculas usam export nomeado (ShadowBox, SimpleTable, MainPageTemplate). Confira o arquivo antes de importar.
  • Busca de dados no cliente: fetch("/api/...") dentro de useEffect, com useState. O React Query só é usado em useThreads e useChatbotAuth. Nunca chame o backend direto do navegador. Passe sempre por uma rota em pages/api/.
  • Busca de dados no servidor: a página importa a função de pages/api/ e chama no getStaticProps/getServerSideProps (ex.: getAllFAQs, getUserGuide).
  • i18n: componentes chamam useTranslation('<namespace>') do next-i18next, e a página carrega os namespaces com serverSideTranslations(locale, [...]). Um namespace novo precisa existir nos três idiomas em public/locales/. Mais em Internacionalização e domínios.
  • Testes: os testes E2E ficam em cypress/. Veja Testes.

Clone this wiki locally