Boilerplate Next.js - Package by Feature

Boilerplate completo com arquitetura package by feature usando Next.js, Supabase, shadcn/ui, React Hook Form + Zod, Context API e Vitest.

🚀 Tecnologias

• Next.js 16 - Framework React com App Router
• Supabase - Backend (Auth, Database)
• shadcn/ui - Componentes UI
• React Hook Form + Zod - Formulários e validação
• Context API - Gerenciamento de estado global
• Vitest - Framework de testes
• Tailwind CSS - Estilização

📁 Estrutura do Projeto

/app
  /api                    # API routes organizadas por feature
    /auth
  /(auth)                 # Rotas de autenticação (login, register)
  /(dashboard)            # Rotas protegidas
  layout.js
  page.js

/features                 # Features organizadas por domínio
  /auth
    /components          # Componentes específicos
    /hooks              # Hooks customizados
    /services           # Lógica de negócio
    /types             # Tipos e schemas Zod
    /utils             # Utilitários específicos
    /__tests__         # Testes da feature
    index.js           # Barrel exports

/shared                   # Recursos compartilhados
  /components           # Componentes UI reutilizáveis
    /ui                # Componentes shadcn/ui
  /hooks               # Hooks compartilhados
  /lib                 # Configurações e clientes
  /utils               # Funções utilitárias
  /context             # Context providers globais

/lib
  /supabase
    client.js          # Cliente Supabase para cliente
    server.js          # Cliente Supabase para servidor
    middleware.js      # Middleware de autenticação

🏗️ Arquitetura Package by Feature

Cada feature contém todos os recursos relacionados em um único local:

• components/ - Componentes React específicos da feature
• hooks/ - Hooks customizados (useAuth, useSession, etc.)
• services/ - Lógica de negócio e chamadas API
• types/ - Tipos TypeScript/JSDoc e schemas Zod
• utils/ - Utilitários específicos da feature
• tests/ - Testes unitários e de integração
• index.js - Barrel exports para facilitar imports

Exemplo de uso:

// Importar tudo de uma feature
import { LoginForm, useAuth, authService, loginSchema } from '@/features/auth';

// Ou importar específico
import { LoginForm } from '@/features/auth/components/LoginForm';

🛠️ Configuração

1. Instalar dependências

npm install

2. Configurar variáveis de ambiente

Crie um arquivo .env.local na raiz do projeto:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your_supabase_publishable_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
NEXT_PUBLIC_APP_URL=http://localhost:3000

Nota: A NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY é a mesma chave que antes era chamada de "anon key". O código mantém compatibilidade com NEXT_PUBLIC_SUPABASE_ANON_KEY como fallback, mas recomenda-se usar a nomenclatura atual.

3. Executar o projeto

npm run dev

Acesse http://localhost:3000

📝 Scripts Disponíveis

npm run dev          # Inicia servidor de desenvolvimento
npm run build        # Build para produção
npm run start        # Inicia servidor de produção
npm run lint         # Executa ESLint
npm run test         # Executa testes com Vitest
npm run test:ui      # Executa testes com UI
npm run test:coverage # Executa testes com coverage

🧪 Testes

O projeto usa Vitest para testes. Exemplos de testes estão em features/auth/__tests__/.

# Executar todos os testes
npm run test

# Executar testes em modo watch
npm run test -- --watch

# Executar testes com coverage
npm run test:coverage

🎨 Componentes UI

Componentes shadcn/ui estão disponíveis em shared/components/ui/. Para adicionar novos componentes:

npx shadcn@latest add [component-name]

🔐 Autenticação

A autenticação é gerenciada pela feature auth:

• LoginForm - Componente de login
• RegisterForm - Componente de registro
• AuthGuard - Componente para proteger rotas
• useAuth - Hook para gerenciar autenticação
• authService - Service com métodos de autenticação

Exemplo de uso:

import { useAuth } from '@/features/auth';

function MyComponent() {
  const { user, signIn, signOut, isAuthenticated } = useAuth();
  
  // ...
}

📦 Adicionando uma Nova Feature

1. Criar estrutura de diretórios:

/features
  /nova-feature
    /components
    /hooks
    /services
    /types
    /utils
    /__tests__
    index.js

2. Criar barrel export em index.js:

export { default as ComponentName } from './components/ComponentName';
export { useCustomHook } from './hooks/useCustomHook';
export { customService } from './services/customService';

3. Usar a feature:

import { ComponentName, useCustomHook } from '@/features/nova-feature';

🎯 Boas Práticas

1. Isolamento: Cada feature deve ser independente
2. Barrel Exports: Use index.js para facilitar imports
3. Tipos: Defina tipos e schemas Zod em types/
4. Testes: Crie testes para cada feature em __tests__/
5. Services: Lógica de negócio deve estar em services/
6. Hooks: Lógica reutilizável deve estar em hooks/

📚 Recursos

• Next.js Documentation
• Supabase Documentation
• shadcn/ui
• React Hook Form
• Zod
• Vitest

📄 Licença

MIT