Repository navigation
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.
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
|
-
atoms/Text/: a tipografia do site.Display,TitleText,LabelTexteBodyTextaplicam fonte, tamanho e altura de linha por uma proptypography(small,medium,large). Use esses em vez de<Text>comfontSizesolto. -
atoms/Link.js: envolve onext/link, mantém olocaleatual e, se ohrefcomeçar comhttp://ouhttps://, abre em nova aba. -
atoms/Button.js,Toggle.js,Checkbox.js: os controles com o visual da BD.
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.
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.
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.
| 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/ChatbotContext.js: provider usado só pela página do chatbot. -
lib/: código só de servidor:authCookie.js(cookietoken) erequireChatbotAuth.js. Detalhes em Arquitetura. -
middlewares/:authUser.jse_middleware.jsnão são importados por nenhum arquivo._middleware.jstambém não roda como middleware do Next, que só procura esse arquivo dentro depages/. -
constants/stripePlans.js: seleção de planos do Stripe. Veja Stripe.
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.
| 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
|
-
Chakra UI v1: o
ChakraProviderusa o tema padrão. Não existeextendTheme, 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 deText/eButton. -
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, comopaymentSystem,imgCrop,toggle,faqebdpro.
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.
-
Nomes de arquivo: componentes em
PascalCase.js. Hooks emcamelCasecom prefixouse, 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 deuseEffect, comuseState. O React Query só é usado emuseThreadseuseChatbotAuth. Nunca chame o backend direto do navegador. Passe sempre por uma rota empages/api/. -
Busca de dados no servidor: a página importa a função de
pages/api/e chama nogetStaticProps/getServerSideProps(ex.:getAllFAQs,getUserGuide). -
i18n: componentes chamam
useTranslation('<namespace>')donext-i18next, e a página carrega os namespaces comserverSideTranslations(locale, [...]). Um namespace novo precisa existir nos três idiomas empublic/locales/. Mais em Internacionalização e domínios. -
Testes: os testes E2E ficam em
cypress/. Veja Testes.