Passo a Passo

Aprenda fazendo

Um guia interativo que te acompanha do setup ao Pull Request. Escolha sua trilha e siga o passo a passo.

01/09

Preparando o ambiente

Fork, clone e instale as dependências para começar a desenvolver.

Acesse o repositório no GitHub e clique em 'Fork' (canto superior direito). Depois clone o seu fork:

Terminal

$git clone https://github.com/SEU-USER/dev-showcase.git

Terminal

$cd dev-showcase

Instale as dependências e inicie o servidor de desenvolvimento:

Terminal

$pnpm install

Terminal

$pnpm dev

▲ Next.js 15.x\n- Local: http://localhost:3000

Crie uma branch a partir de develop:

Terminal

$git checkout develop && git checkout -b feature/nome-da-feature

Dúvidas comuns

02/09

Entendendo a estrutura

Conheça as pastas principais e onde cada tipo de código vive.

Clique nas pastas para explorar a estrutura do projeto:

Código-fonte principal da aplicação

Arquivos de tradução por idioma (pt-BR, en, es, de)

Dúvidas comuns

03/09

Criando a feature

Crie o componente principal. O projeto tem dois caminhos: páginas dinâmicas (guides/implementações) e standalone.

Qual tipo de página você quer criar?

O projeto tem dois caminhos: páginas dinâmicas (que aparecem em /dicas, /implementacoes ou /ferramentas automaticamente) e páginas standalone (como as de /contribua). Escolha o caminho certo para sua feature.

Página dinâmica (guide, implementação ou ferramenta)

Páginas dinâmicas são roteadas automaticamente via slug. Você só precisa criar o componente — a rota já existe em /dicas/[slug], /implementacoes/[slug] ou /ferramentas/[slug].

1. Crie o componente (named export obrigatório)

Pasta em kebab-case: graphql-tips/ (não GraphqlTips/)

src/features/guides/graphql-tips/index.tsx

"use client";
 
import { useTranslations } from "next-intl";
 
import { HeroSection } from "@/components/hero-section";
import { SectionWrapper } from "@/components/section-wrapper";
 
export function GraphqlTips() {
  const t = useTranslations("graphqlTipsPage");
 
  return (
    <div className="min-h-screen">
      <HeroSection
        badge={t("hero.badge")}
        title={t("hero.title")}
        description={t("hero.description")}
        showBackLink
        backHref="/dicas"
      />
      <SectionWrapper id="content">
        {/* Conteúdo aqui */}
      </SectionWrapper>
    </div>
  );
}

Páginas dinâmicas NÃO precisam de page.tsx ou loading.tsx próprios — a rota dinâmica [slug]/page.tsx já existe. O próximo passo (Registro) mostra como conectar seu componente ao sistema.

Página standalone (/contribua/...)

Para páginas fora do sistema dinâmico (ex: seções do /contribua), você precisa criar a rota manualmente:

1. Crie o componente da feature

src/features/contribute/minha-feature/index.tsx

"use client";
 
import { useTranslations } from "next-intl";
 
import { HeroSection } from "@/components/hero-section";
import { SectionWrapper } from "@/components/section-wrapper";
 
export function MinhaFeaturePage() {
  const t = useTranslations("minhaFeaturePage");
 
  return (
    <div className="min-h-screen">
      <HeroSection
        badge={t("hero.badge")}
        title={t("hero.title")}
        description={t("hero.description")}
        showBackLink
        backHref="/contribua"
      />
      <SectionWrapper id="content">
        {/* Conteúdo aqui */}
      </SectionWrapper>
    </div>
  );
}

2. Registre a rota (page.tsx)

src/app/contribua/minha-feature/page.tsx

import { Metadata } from "next";
import { getLocale, getTranslations } from "next-intl/server";
 
import { MinhaFeaturePage } from "@/features/contribute/minha-feature";
import { buildPageMetadata } from "@/lib/seo";
 
export async function generateMetadata(): Promise<Metadata> {
  const [t, locale] = await Promise.all([
    getTranslations("minhaFeaturePage.meta"),
    getLocale(),
  ]);
  return buildPageMetadata({
    title: t("title"),
    description: t("description"),
    path: "/contribua/minha-feature",
    locale,
  });
}
 
export default function Page() {
  return <MinhaFeaturePage />;
}

3. Adicione o loading skeleton

src/app/contribua/minha-feature/loading.tsx

import { PageSkeleton } from "@/components/page-skeleton";
 
export default function Loading() {
  return <PageSkeleton />;
}

Dúvidas comuns

04/09

Registro & Integração

Conecte seu componente ao sistema de rotas, busca e navegação do projeto.

Sistema de páginas dinâmicas

O projeto usa um sistema centralizado: o componente é registrado uma vez e automaticamente ganha rota, SEO, busca e listagem.

Registre em content.ts

Adicione seu conteúdo no array CONTENT_ITEMS. O slug vira a URL, a category define em qual seção aparece.

src/data/content.ts

// src/data/content.ts
export const CONTENT_ITEMS: ContentItem[] = [
  // ... itens existentes ...
  {
    slug: "graphql-tips",
    title: "GraphQL Tips — Guia Prático",
    description: "Guia completo de GraphQL...",
    component: "GraphqlTips",
    category: "guide",
  },
];

Adicione ao COMPONENT_MAP

Conecte o nome do componente (string do content.ts) ao import dinâmico real. Use lazy loading com next/dynamic.

src/lib/content/component-map.ts

// src/lib/content/component-map.ts
const COMPONENT_MAP: Record<string, React.ComponentType<unknown>> = {
  // ... componentes existentes ...
  GraphqlTips: dynamic(() =>
    import("@/features/guides/graphql-tips").then(
      (m) => m.GraphqlTips,
    ),
  ),
};

Vincule no buscar do site

Para sua página aparecer na busca global (Ctrl+K), faça os dois passos abaixo. Sem isso, quem usar o buscador do site não encontra sua página.

Como funciona: o sistema monta os resultados a partir do content.ts; o título e a descrição vêm dos search.json (um por idioma); as palavras-chave vêm do tagMap. Por isso os dois arquivos são obrigatórios.

Sem search.json e tagMap, a página não entra nos resultados da busca.

messages/pt-BR/search.json (e en, es, de)

// messages/pt-BR/search.json → items
{
  "graphql-tips": {
    "title": "GraphQL Tips — Guia Prático",
    "description": "Guia completo de GraphQL..."
  }
}

src/components/global-search/search-data.ts (tagMap)

// src/components/global-search/search-data.ts — tagMap (dentro de buildTags)
const tagMap: Record<string, string[]> = {
  // ... outros slugs ...
  "graphql-tips": ["graphql", "api", "query", "guia"],
};

Checklist — depois de editar, confira:

search.json preenchido nos 4 idiomas (pt-BR, en, es, de) com items.{slug}'.title e .description
tagMap em search-data.ts com o slug e as tags (palavras que o usuário digitaria ao procurar)
system-prompt.ts: adicione a página na seção PÁGINAS para o chatbot poder recomendá-la
Testar: abra a busca (Ctrl+K) e digite o título ou uma tag da sua página

Adicione ícone à listagem

Cada página da listagem (/dicas, /implementacoes) usa um iconMap para exibir ícones. Adicione o slug e um ícone do Lucide.

src/app/dicas/page.tsx

// src/app/dicas/page.tsx
const iconMap = {
  // ... ícones existentes ...
  "graphql-tips": Workflow,  // import de lucide-react
};

Categorias disponíveis

guide

Guias e dicas → aparece em /dicas/[slug]

implementation

Implementações reais → aparece em /implementacoes/[slug]

tool

Ferramentas interativas → aparece em /ferramentas/[slug]

Guia completo (loading, nav, changelog): docs/content-management/ADDING_PAGES.md

Dúvidas comuns

05/09

Desenvolvendo

Padrões de código, componentes disponíveis e boas práticas do projeto.

Padrões que seguimos

TypeScript strict — nada de any, tipos explícitos
Componentes funcionais com arrow functions ou function declarations
Imports com alias @/ (ex: @/components/ui/button)
Todo texto visível usa i18n (next-intl) — nunca hardcode
Acessibilidade: aria-labels, roles semânticos, navegação por teclado
Framer Motion para animações de entrada (AnimatedSection)
Código limpo — funções e componentes concisos, nada extenso demais
JSDoc em português em componentes, funções, hooks e tipos
Nomenclatura clara e autoexplicativa — fácil entendimento

Componentes disponíveis

Reutilize os componentes do Design System. Consulte o catálogo completo em /contribua/design-system.

Dúvidas comuns

06/09

Traduções (i18n)

Todo texto visível precisa ser traduzido. pt-BR é a fonte de verdade.

Fluxo de tradução

1
Crie as chaves em messages/pt-BR/seuNamespace.json
2
Registre o namespace em messages/pt-BR/index.ts (e nos outros idiomas) e em src/lib/i18n/load-messages.ts (array NAMESPACES)
3
Adicione o tipo em src/lib/i18n/types.d.ts
4
Adicione título e descrição em messages/*/search.json (para a busca global)
5
Se adicionou ao nav, atualize messages/*/nav.json com label e descrição
6
Crie os arquivos nos outros 3 idiomas (en, es, de) ou use pnpm translate
7
Use useTranslations('seuNamespace') no componente

Exemplo de uso

messages/*.json

// messages/pt-BR/myNamespace.json
{
  "title": "Meu título",
  "description": "Descrição do componente"
}
 
// messages/en/myNamespace.json
{
  "title": "My title",
  "description": "Component description"
}

component.tsx

// Client Component
"use client";
import { useTranslations } from "next-intl";
 
export function MyComponent() {
  const t = useTranslations("myNamespace");
  return <h1>{t("title")}</h1>;
}
 
// Server Component
import { getTranslations } from "next-intl/server";
 
export async function MyServerComponent() {
  const t = await getTranslations("myNamespace");
  return <h1>{t("title")}</h1>;
}

Dica

O script pnpm translate pode ajudar a gerar traduções automáticas via DeepL para os outros idiomas.

Dúvidas comuns

08/09

Qualidade

Lint, testes e build devem passar antes de abrir o PR.

Comandos essenciais

Verifica padrões de código e imports

Terminal

$pnpm lint

✓ No ESLint warnings or errors

Executa testes unitários e de componentes

Terminal

$pnpm test

✓ All tests passed

Build completa — valida TypeScript e SSR

Terminal

$pnpm build

✓ Compiled successfully\n✓ Generating static pages\n✓ Finalizing page optimization

Todos devem passar sem erros antes do PR.

Dúvidas comuns

09/09

Pull Request

Hora de enviar sua contribuição para review!

Commit com Conventional Commits

Use o formato padrão. Exemplos:

conventional commits

feat: add tutorial page
fix: correct translation key for navbar
docs: update README with setup instructions

Push e PR

Terminal

$git add . && git commit -m "feat: my awesome feature"

Terminal

$git push -u origin HEAD

Terminal

$gh pr create --base develop

O PR deve incluir:

Título claro descrevendo a mudança
Descrição do que foi feito e por quê
Screenshots se houver mudanças visuais
Checklist de testes realizados

Parabéns! Sua contribuição está a caminho. Após o review, seu código entra na plataforma.

Dúvidas comuns

Voltar

Passo a Passo

Aprenda fazendo

Um guia interativo que te acompanha do setup ao Pull Request. Escolha sua trilha e siga o passo a passo.

01/09

Preparando o ambiente

Fork, clone e instale as dependências para começar a desenvolver.

Acesse o repositório no GitHub e clique em 'Fork' (canto superior direito). Depois clone o seu fork:

Terminal

$git clone https://github.com/SEU-USER/dev-showcase.git

Terminal

$cd dev-showcase

Instale as dependências e inicie o servidor de desenvolvimento:

Terminal

$pnpm install

Terminal

$pnpm dev

▲ Next.js 15.x\n- Local: http://localhost:3000

Crie uma branch a partir de develop:

Terminal

$git checkout develop && git checkout -b feature/nome-da-feature

Dúvidas comuns

02/09

Entendendo a estrutura

Conheça as pastas principais e onde cada tipo de código vive.

Clique nas pastas para explorar a estrutura do projeto:

Código-fonte principal da aplicação

Arquivos de tradução por idioma (pt-BR, en, es, de)

Dúvidas comuns

03/09

Criando a feature

Crie o componente principal. O projeto tem dois caminhos: páginas dinâmicas (guides/implementações) e standalone.

Qual tipo de página você quer criar?

Página dinâmica (guide, implementação ou ferramenta)

Páginas dinâmicas são roteadas automaticamente via slug. Você só precisa criar o componente — a rota já existe em /dicas/[slug], /implementacoes/[slug] ou /ferramentas/[slug].

1. Crie o componente (named export obrigatório)

Pasta em kebab-case: graphql-tips/ (não GraphqlTips/)

src/features/guides/graphql-tips/index.tsx

"use client";
 
import { useTranslations } from "next-intl";
 
import { HeroSection } from "@/components/hero-section";
import { SectionWrapper } from "@/components/section-wrapper";
 
export function GraphqlTips() {
  const t = useTranslations("graphqlTipsPage");
 
  return (
    <div className="min-h-screen">
      <HeroSection
        badge={t("hero.badge")}
        title={t("hero.title")}
        description={t("hero.description")}
        showBackLink
        backHref="/dicas"
      />
      <SectionWrapper id="content">
        {/* Conteúdo aqui */}
      </SectionWrapper>
    </div>
  );
}

Páginas dinâmicas NÃO precisam de page.tsx ou loading.tsx próprios — a rota dinâmica [slug]/page.tsx já existe. O próximo passo (Registro) mostra como conectar seu componente ao sistema.

Página standalone (/contribua/...)

Para páginas fora do sistema dinâmico (ex: seções do /contribua), você precisa criar a rota manualmente:

1. Crie o componente da feature

src/features/contribute/minha-feature/index.tsx

"use client";
 
import { useTranslations } from "next-intl";
 
import { HeroSection } from "@/components/hero-section";
import { SectionWrapper } from "@/components/section-wrapper";
 
export function MinhaFeaturePage() {
  const t = useTranslations("minhaFeaturePage");
 
  return (
    <div className="min-h-screen">
      <HeroSection
        badge={t("hero.badge")}
        title={t("hero.title")}
        description={t("hero.description")}
        showBackLink
        backHref="/contribua"
      />
      <SectionWrapper id="content">
        {/* Conteúdo aqui */}
      </SectionWrapper>
    </div>
  );
}

2. Registre a rota (page.tsx)

src/app/contribua/minha-feature/page.tsx

import { Metadata } from "next";
import { getLocale, getTranslations } from "next-intl/server";
 
import { MinhaFeaturePage } from "@/features/contribute/minha-feature";
import { buildPageMetadata } from "@/lib/seo";
 
export async function generateMetadata(): Promise<Metadata> {
  const [t, locale] = await Promise.all([
    getTranslations("minhaFeaturePage.meta"),
    getLocale(),
  ]);
  return buildPageMetadata({
    title: t("title"),
    description: t("description"),
    path: "/contribua/minha-feature",
    locale,
  });
}
 
export default function Page() {
  return <MinhaFeaturePage />;
}

3. Adicione o loading skeleton

src/app/contribua/minha-feature/loading.tsx

import { PageSkeleton } from "@/components/page-skeleton";
 
export default function Loading() {
  return <PageSkeleton />;
}

Dúvidas comuns

04/09

Registro & Integração

Conecte seu componente ao sistema de rotas, busca e navegação do projeto.

Sistema de páginas dinâmicas

O projeto usa um sistema centralizado: o componente é registrado uma vez e automaticamente ganha rota, SEO, busca e listagem.

Registre em content.ts

Adicione seu conteúdo no array CONTENT_ITEMS. O slug vira a URL, a category define em qual seção aparece.

src/data/content.ts

// src/data/content.ts
export const CONTENT_ITEMS: ContentItem[] = [
  // ... itens existentes ...
  {
    slug: "graphql-tips",
    title: "GraphQL Tips — Guia Prático",
    description: "Guia completo de GraphQL...",
    component: "GraphqlTips",
    category: "guide",
  },
];

Adicione ao COMPONENT_MAP

Conecte o nome do componente (string do content.ts) ao import dinâmico real. Use lazy loading com next/dynamic.

src/lib/content/component-map.ts

// src/lib/content/component-map.ts
const COMPONENT_MAP: Record<string, React.ComponentType<unknown>> = {
  // ... componentes existentes ...
  GraphqlTips: dynamic(() =>
    import("@/features/guides/graphql-tips").then(
      (m) => m.GraphqlTips,
    ),
  ),
};

Vincule no buscar do site

Para sua página aparecer na busca global (Ctrl+K), faça os dois passos abaixo. Sem isso, quem usar o buscador do site não encontra sua página.

Sem search.json e tagMap, a página não entra nos resultados da busca.

messages/pt-BR/search.json (e en, es, de)

// messages/pt-BR/search.json → items
{
  "graphql-tips": {
    "title": "GraphQL Tips — Guia Prático",
    "description": "Guia completo de GraphQL..."
  }
}

src/components/global-search/search-data.ts (tagMap)

// src/components/global-search/search-data.ts — tagMap (dentro de buildTags)
const tagMap: Record<string, string[]> = {
  // ... outros slugs ...
  "graphql-tips": ["graphql", "api", "query", "guia"],
};

Checklist — depois de editar, confira:

search.json preenchido nos 4 idiomas (pt-BR, en, es, de) com items.{slug}'.title e .description
tagMap em search-data.ts com o slug e as tags (palavras que o usuário digitaria ao procurar)
system-prompt.ts: adicione a página na seção PÁGINAS para o chatbot poder recomendá-la
Testar: abra a busca (Ctrl+K) e digite o título ou uma tag da sua página

Adicione ícone à listagem

Cada página da listagem (/dicas, /implementacoes) usa um iconMap para exibir ícones. Adicione o slug e um ícone do Lucide.

src/app/dicas/page.tsx

// src/app/dicas/page.tsx
const iconMap = {
  // ... ícones existentes ...
  "graphql-tips": Workflow,  // import de lucide-react
};

Categorias disponíveis

guide

Guias e dicas → aparece em /dicas/[slug]

implementation

Implementações reais → aparece em /implementacoes/[slug]

tool

Ferramentas interativas → aparece em /ferramentas/[slug]

Guia completo (loading, nav, changelog): docs/content-management/ADDING_PAGES.md

Dúvidas comuns

05/09

Desenvolvendo

Padrões de código, componentes disponíveis e boas práticas do projeto.

Padrões que seguimos

TypeScript strict — nada de any, tipos explícitos
Componentes funcionais com arrow functions ou function declarations
Imports com alias @/ (ex: @/components/ui/button)
Todo texto visível usa i18n (next-intl) — nunca hardcode
Acessibilidade: aria-labels, roles semânticos, navegação por teclado
Framer Motion para animações de entrada (AnimatedSection)
Código limpo — funções e componentes concisos, nada extenso demais
JSDoc em português em componentes, funções, hooks e tipos
Nomenclatura clara e autoexplicativa — fácil entendimento

Componentes disponíveis

Reutilize os componentes do Design System. Consulte o catálogo completo em /contribua/design-system.

Dúvidas comuns

06/09

Traduções (i18n)

Todo texto visível precisa ser traduzido. pt-BR é a fonte de verdade.

Fluxo de tradução

1
Crie as chaves em messages/pt-BR/seuNamespace.json
2
Registre o namespace em messages/pt-BR/index.ts (e nos outros idiomas) e em src/lib/i18n/load-messages.ts (array NAMESPACES)
3
Adicione o tipo em src/lib/i18n/types.d.ts
4
Adicione título e descrição em messages/*/search.json (para a busca global)
5
Se adicionou ao nav, atualize messages/*/nav.json com label e descrição
6
Crie os arquivos nos outros 3 idiomas (en, es, de) ou use pnpm translate
7
Use useTranslations('seuNamespace') no componente

Exemplo de uso

messages/*.json

// messages/pt-BR/myNamespace.json
{
  "title": "Meu título",
  "description": "Descrição do componente"
}
 
// messages/en/myNamespace.json
{
  "title": "My title",
  "description": "Component description"
}

component.tsx

// Client Component
"use client";
import { useTranslations } from "next-intl";
 
export function MyComponent() {
  const t = useTranslations("myNamespace");
  return <h1>{t("title")}</h1>;
}
 
// Server Component
import { getTranslations } from "next-intl/server";
 
export async function MyServerComponent() {
  const t = await getTranslations("myNamespace");
  return <h1>{t("title")}</h1>;
}

Dica

O script pnpm translate pode ajudar a gerar traduções automáticas via DeepL para os outros idiomas.

Dúvidas comuns

08/09

Qualidade

Lint, testes e build devem passar antes de abrir o PR.

Comandos essenciais

Verifica padrões de código e imports

Terminal

$pnpm lint

✓ No ESLint warnings or errors

Executa testes unitários e de componentes

Terminal

$pnpm test

✓ All tests passed

Build completa — valida TypeScript e SSR

Terminal

$pnpm build

✓ Compiled successfully\n✓ Generating static pages\n✓ Finalizing page optimization

Todos devem passar sem erros antes do PR.

Dúvidas comuns

09/09

Pull Request

Hora de enviar sua contribuição para review!

Commit com Conventional Commits

Use o formato padrão. Exemplos:

conventional commits

feat: add tutorial page
fix: correct translation key for navbar
docs: update README with setup instructions

Push e PR

Terminal

$git add . && git commit -m "feat: my awesome feature"

Terminal

$git push -u origin HEAD

Terminal

$gh pr create --base develop

O PR deve incluir:

Título claro descrevendo a mudança
Descrição do que foi feito e por quê
Screenshots se houver mudanças visuais
Checklist de testes realizados

Parabéns! Sua contribuição está a caminho. Após o review, seu código entra na plataforma.

Aprenda fazendo

Criar feature nova

Melhorar existente

Preparando o ambiente

Dúvidas comuns

Como faço o fork no GitHub?

Qual versão do Node.js preciso?

Posso usar npm ou yarn?

O que é a branch develop?

pnpm install deu erro, o que fazer?

Entendendo a estrutura

Dúvidas comuns

Onde crio meu componente?

O que é a pasta features/?

Onde ficam os estilos?

O que é content.ts e lib/content/?

Preciso criar uma pasta para cada feature nova?

Criando a feature

Página dinâmica (guide, implementação ou ferramenta)

1. Crie o componente (named export obrigatório)

Página standalone (/contribua/...)

1. Crie o componente da feature

2. Registre a rota (page.tsx)

3. Adicione o loading skeleton

Dúvidas comuns

Client ou Server Component?

Qual caminho escolher: dinâmico ou standalone?

Preciso criar page.tsx para páginas dinâmicas?

Registro & Integração

Registre em content.ts

Adicione ao COMPONENT_MAP

Vincule no buscar do site

Checklist — depois de editar, confira:

Adicione ícone à listagem

Categorias disponíveis

Dúvidas comuns

O que acontece se eu esquecer o COMPONENT_MAP?

Preciso adicionar ao nav (menu de navegação)?

Como funciona o SEO automático?

Como testo se o registro funcionou?

E para páginas standalone (/contribua)?

Esqueci de colocar no search.json ou no tagMap. O que acontece?

Desenvolvendo

Padrões que seguimos

Componentes disponíveis

Dúvidas comuns

Posso instalar novas dependências?

Como uso animações?

Onde vejo os componentes disponíveis?

Traduções (i18n)

Fluxo de tradução

Exemplo de uso

Dúvidas comuns

Posso contribuir só em pt-BR?

O que é um namespace?

Como uso traduções em Server Components?

Acessibilidade

Checklist de acessibilidade

Dúvidas comuns

O que é ARIA?

Como testo acessibilidade?

Preciso adicionar skip links?

Qualidade

Comandos essenciais

Dúvidas comuns

O lint falhou, e agora?

Preciso adicionar testes?

O build deu erro de tipo, o que fazer?

O teste falhou em algo que não mexi, o que fazer?

Preciso rodar os 3 comandos toda vez?

Pull Request

Commit com Conventional Commits

Push e PR

O PR deve incluir:

Dúvidas comuns

Qual o formato do título do commit?

Quem revisa meu PR?

Posso fazer mais de um commit no PR?

E se meu PR tiver conflitos?

Quanto tempo leva o review?