next-template resumo do projeto

Este repositório é um template de documentação/site construído com Next.js (App Router) e MDX. O objetivo principal é fornecer uma base para páginas de documentação e conteúdo em MDX com componentes UI reutilizáveis.

Resumo rápido:

• Tipo: Template / Starter para documentação e site de componentes.
• Framework: Next.js (App Router) com TypeScript.
• Conteúdo: Páginas em MDX (content/*.mdx) e guia/ documentação em docs/.

Rodando localmente

• Instalar dependências:

npm install

• Desenvolvimento:

npm run dev

• Build e start:

npm run build
npm run start

• Lint / format:

npm run lint
npm run format
npm run format:check

Principais tecnologias

• next (v16 App Router)
• react / react-dom (v19)
• typescript
• tailwindcss v4 + @tailwindcss/postcss
• @next/mdx, @mdx-js/* para MDX
• remark / rehype plugins (remark-gfm, rehype-katex, rehype-slug)
• radix-ui primitives e shadcn-style components

Scripts (em package.json)

• dev: next dev roda o servidor de desenvolvimento
• build: next build build para produção
• start: next start serve a build
• lint: eslint linter
• format: prettier --write . formata o código
• format:check: prettier --check . checa formatação

Estrutura principal do projeto

• app/ rotas da App Router do Next.js (Server Components por padrão).
  • app/page.tsx página inicial.
  • app/[slug]/page.tsx roteamento dinâmico que importa MDX dinâmico para páginas de conteúdo.
  • app/[slug]/layout.tsx layout das páginas de conteúdo.
• content/ arquivos MDX principais (ex.: welcome.mdx, account.mdx) que viram páginas.
• docs/ documentação agrupada por tópicos (ex.: next.js/, shadcn-ui/).
• components/ componentes React reutilizáveis e UI primitives.
  • components/docs-search.tsx componente de busca por docs.
  • components/app-sidebar.tsx sidebar do app.
  • components/ui/ primitives UI (botões, diálogos, inputs, etc.).
• lib/ utilitários e helpers relacionados a MDX e navegação.
  • lib/mdx.ts helpers para descobrir/importar MDX, indexação e busca.
  • lib/sidebarItems.js dados de navegação para sidebar.
• hooks/ hooks customizados (ex.: use-mobile.ts).
• public/ ativos estáticos.
• postcss.config.mjs, next.config.ts, tsconfig.json configurações principais.

Pontos importantes sobre MDX e rotas

• Conteúdo MDX exporta metadata (frontmatter) usado pelas páginas. Ex.: export const metadata = { title, description }.
• app/[slug]/page.tsx importa módulos MDX dinamicamente: const mod = await import('@/content/welcome.mdx') e usa mod.metadata.
• Mantenha generateStaticParams() em app/[slug]/page.tsx quando necessário para SSG e controle de rotas dinâmicas.

Server vs Client

• Arquivos em app/ são Server Components por padrão. Use "use client" somente em componentes interativos.
• Evite misturar imports server-only em componentes client.

Onde editar / adicionar conteúdo

• Adicionar uma página MDX: colocar my-page.mdx em content/ e exportar metadata no arquivo MDX.
• Atualizar navegação: editar lib/sidebarItems.js e o componente components/app-sidebar.tsx renderará os itens.
• Tenant welcome page: ao criar um novo diretório de tenant em content/, inclua um arquivo welcome.mdx. O nome do arquivo deve ser em inglês (welcome.mdx) e o conteúdo da página deve ser escrito em Português do Brasil (pt-BR). Isso garante uma página de entrada padronizada para cada tenant na navegação do site.

Arquivos e convenções úteis

• package.json dependências e scripts.
• next.config.ts config do Next.
• lib/mdx.ts indexador e helpers MDX.
• app/[slug]/page.tsx rota dinâmica de MDX.
• components/docs-search.tsx busca integrada.
• components/app-sidebar.tsx sidebar e navegação.
• lib/sidebarItems.js configuração do menu lateral.

Boas práticas e dicas

• Use metadata exportado nos MDX para título/descrição em vez de parsing do HTML.
• Teste builds (npm run build) após alterar rotas/MDX para validar SSG e tipagens.
• Preserve Server/Client boundaries e evite usar use client desnecessariamente.

Contribuição e commits

• Siga o formato Conventional Commits (ex.: feat(auth): add user registration endpoint).
• Diretrizes de commit estão em .github/instructions/commit.instructions.md.
• Instruções específicas do template (MDX, rotas, sidebar) em .github/copilot-instructions.md.

Se quiser, eu posso:

• rodar uma verificação automática dos arquivos principais e gerar um sumário mais detalhado por arquivo;
• criar exemplos de novos MDX ou ajustar generateStaticParams() para conteúdos adicionais.

Informe qual dessas opções prefere para eu continuar.

AI / Copilot guidance 🤖

• Este repositório inclui instruções para agentes AI em .github/copilot-instructions.md — leia esse arquivo antes de automatizar mudanças.
• Para mudanças de conteúdo (MDX), verifique frontmatter e execute npm run lint / npm run build localmente antes de abrir PR.
• Peça uma PR focada (por exemplo: "adicionar content/municipay/new-page.mdx") e eu posso gerar a PR com commit seguindo Conventional Commits.