npm package: @josefsaaas/boilerplate
Description: Boilerplate completo com arquitetura **package by feature** usando Next.js, Supabase, shadcn/ui, React Hook Form + Zod, Context API e Vitest.
Latest version: 6.0.0

# 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:

```javascript
// 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

```bash
npm install
```

### 2. Configurar variáveis de ambiente

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

```env
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

```bash
npm run dev
```

Acesse [http://localhost:3000](http://localhost:3000)

## 📝 Scripts Disponíveis

```bash
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__/`.

```bash
# 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:

```bash
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:

```javascript
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`:

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

3. Usar a feature:

```javascript
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](https://nextjs.org/docs)
- [Supabase Documentation](https://supabase.com/docs)
- [shadcn/ui](https://ui.shadcn.com/)
- [React Hook Form](https://react-hook-form.com/)
- [Zod](https://zod.dev/)
- [Vitest](https://vitest.dev/)

## 📄 Licença

MIT