diegofornalha nextjs-nextui .cursorrules file for TypeScript

# Desenvolvimento Cross-Platform com TypeScript e React

## Diretrizes Gerais de Simplificação

### 1. Remova Complexidade Desnecessária

- Elimine código redundante
- Remova funcionalidades não utilizadas
- Simplifique lógicas complexas
- Evite over-engineering
- manter logs extremamentes necessários
- Ocultar logs de sucesso (200)
- Ocultar mensagens de compilação
- Ocultar o aviso experimental do Node.js
- Manter apenas mensagens de erro importantes

### 2. Gerencie Dependências com Cuidado

- Mantenha apenas dependências essenciais
- Avalie o custo/benefício de cada pacote
- Prefira soluções nativas quando possível
- Remova dependências não utilizadas

### 3. Mantenha o Projeto Limpo

- Apague arquivos e pastas não utilizados
- Remova código comentado
- Mantenha apenas assets necessários
- Faça limpeza regular do projeto

### 4. Simplifique o package.json

- Remova scripts não utilizados
- Mantenha apenas exportações necessárias
- Organize scripts de forma clara
- Mantenha versões de dependências atualizadas

### 5. Desenvolva Componentes Eficientes

- Mantenha componentes simples e focados
- Evite props desnecessárias
- Use composição ao invés de herança
- Documente funcionalidades importantes

### 6. Monitore Padrões de Problemas

- Identifique loops de correções
- Documente soluções recorrentes
- Corrija problemas na raiz
- Evite soluções temporárias

## Processo de Desenvolvimento Incremental

1. **Evolução Gradual**:

   - Comece com uma única página funcional.
   - Adicione um componente por vez.
   - Teste cada adição antes de avançar.
   - Só adicione dependências quando absolutamente necessário.

2. **Regras de Ouro**:

   - Não adicione dependências desnecessárias.
   - Mantenha a simplicidade sempre.
   - Realize testes frequentes.
   - Faça commits pequenos e regulares.

3. **Quando Precisar Escalar**:
   - Use monorepo apenas se for realmente necessário.
   - Adicione ferramentas conforme a necessidade real.
   - Mantenha a documentação atualizada.
   - Faça mudanças incrementais.

## Configuração Inicial

### Remover Avisos Desnecessários

Para remover avisos de desenvolvimento desnecessários, configure o `next.config.js`:

```typescript
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

module.exports = nextConfig;
```

### Configurar .gitignore

Mantenha o .gitignore limpo e relevante para seu projeto:

#### ✅ Regras para um .gitignore Eficiente:

1. **Mantenha Apenas o Necessário**

   - Inclua somente padrões para arquivos que existem ou podem existir no projeto
   - Remova entradas de tecnologias que não está usando
   - Evite duplicação de padrões

2. **Organize por Categorias**

   - Agrupe entradas relacionadas (ex: dependências, build, ambiente)
   - Use comentários para identificar cada seção
   - Mantenha uma ordem lógica

3. **Revise Regularmente**

   - Remova padrões de ferramentas que não usa mais
   - Atualize conforme o projeto evolui
   - Questione se cada entrada é realmente necessária

4. **Padrões Essenciais para Next.js**

   ```plaintext
   # Dependências
   node_modules

   # Next.js
   .next/

   # Ambiente
   .env*.local
   .env

   # Debug
   npm-debug.log*
   yarn-debug.log*
   yarn-error.log*

   # TypeScript
   *.tsbuildinfo
   next-env.d.ts

   # Sistema
   .DS_Store

   # Logs
   *.log
   ```

#### ❌ Evite no .gitignore:

- Padrões de ferramentas que não usa
- Duplicação de regras
- Entradas muito genéricas
- Padrões de outras tecnologias/frameworks

### Criar um Projeto Next.js Básico

```bash
npx create-next-app@latest meu-projeto --typescript --tailwind --eslint
cd meu-projeto
npm run dev
```

### Estrutura Inicial Recomendada

```plaintext
meu-projeto/
├── src/
│   ├── components/ # Componentes reutilizáveis
│   ├── pages/      # Páginas do Next.js
│   └── styles/     # Estilos globais
├── package.json
└── tsconfig.json
```

### Página Inicial

Crie uma página simples em `src/pages/index.tsx`:

```tsx
export default function Home() {
  return <h1>Bem-vindo ao meu projeto Next.js!</h1>;
}
```

### Adicionar Componentes Básicos

Exemplo: `src/components/Button.tsx`

```tsx
import React from "react";

interface ButtonProps {
  label: string;
  onClick: () => void;
}

const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return (
    <button onClick={onClick} className="bg-blue-500 text-white p-2 rounded">
      {label}
    </button>
  );
};

export default Button;
```

### Estilização com Tailwind CSS

Adicione estilos globais em `src/styles/globals.css`:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

## Boas Práticas

### ✅ Faça:

- Comece com o mínimo necessário.
- Adicione funcionalidades uma por vez.
- Teste cada nova adição.
- Use TypeScript desde o início.
- Use Tailwind CSS para estilização.

### ❌ Não Faça:

- Não adicione dependências desnecessárias.
- Não crie estruturas complexas sem necessidade.
- Não use monorepo sem necessidade clara.
- Não misture múltiplas tecnologias de UI.
- Não tente implementar tudo de uma vez.

## Processo de Desenvolvimento

1. **Crie um Componente**
2. **Teste o Componente**
3. **Integre na Página**
4. **Teste Novamente**
5. **Faça o Commit**
6. **Repita o Ciclo**

## Estrutura Mínima Recomendada

```plaintext
src/
├── pages/
│   └── index.tsx # Apenas uma página inicial
└── components/
    └── Button.tsx # Um componente por vez
```

## Checklist Antes de Adicionar Algo Novo

- Isso é realmente necessário agora?
- Existe uma solução mais simples?
- Isso vai adicionar complexidade?
- Vale a pena o trade-off?

## Sinais de Alerta

- Muitos arquivos de configuração.
- Dependências não utilizadas.
- Arquivos vazios.
- Imports não utilizados.
- Código comentado em excesso.
- IDEs mostrando erros de dependências mesmo após instalação:
  - Este é um problema comum onde a IDE não reconhece imediatamente novas dependências
  - Solução: Feche e reabra o navegador/IDE
  - Na maioria dos casos, os erros desaparecem após reiniciar a IDE
  - Não é necessário reinstalar as dependências nestes casos

## Conclusão

- A simplicidade é a chave.
- Cada linha de código é uma responsabilidade.
- Menos é mais.
- Comece pequeno e cresça conforme necessário.
- Mantenha o projeto limpo e organizado.

### Estrutura Recomendada do Projeto

```plaintext
projeto/
├── .next/                  # ⚠️ no .gitignore
├── node_modules/          # ⚠️ no .gitignore
├── src/
│   ├── @types/
│   └── next-pwa.d.ts
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   └── Button.tsx
│   └── utils/
│       └── platform.ts
├── .cursorrules
├── .gitattributes
├── .gitignore
├── eslint.config.mjs
├── next-env.d.ts
├── next.config.js
├── next.config.ts
├── package-lock.json
├── package.json
├── postcss.config.mjs
├── README.md
├── tailwind.config.ts
└── tsconfig.json
```

### Descrição da Estrutura

- **src/@types/**: Definições de tipos TypeScript
- **src/app/**: Componentes e layouts principais (App Router)
- **src/components/**: Componentes reutilizáveis
- **src/utils/**: Funções utilitárias e helpers
- **Diretórios Ignorados**:
  - `.next/`: Build e cache do Next.js (ignorado no git)
  - `node_modules/`: Dependências do projeto (ignorado no git)
- **Arquivos de Configuração**:
  - `next.config.js`: Configuração do Next.js
  - `tailwind.config.ts`: Configuração do Tailwind CSS
  - `tsconfig.json`: Configuração do TypeScript
  - `.gitignore`: Arquivos a serem ignorados pelo Git

# Ambiente de Desenvolvimento

- Sistema Operacional: macOS
- Gerenciador de Pacotes do Sistema: Homebrew (brew)
- Gerenciador de Pacotes Node: Yarn (exclusivamente)

## Gerenciamento de Dependências

### ✅ Usar Apenas Yarn 4 (Berry)

```bash
yarn deps:outdated      # Verificar e atualizar dependências interativamente
yarn up -i             # Alternativa direta para verificar atualizações
yarn up [pacote]       # Atualizar um pacote específico
yarn add [pacote]      # Instalar nova dependência
yarn add -D [pacote]   # Instalar dependência de desenvolvimento
yarn remove [pacote]   # Remover dependência
yarn                   # Instalar todas as dependências
yarn dedupe           # Remove duplicações de pacotes e otimiza dependências
```

### Comandos Específicos do Yarn 4

- `yarn up -i`: Interface interativa para atualização de dependências
- `yarn up "*" --latest`: Atualizar todas as dependências para última versão
- `yarn dlx`: Executar pacotes sem instalá-los (substitui npx)
- `yarn why [pacote]`: Verificar por que um pacote está instalado
- `yarn info [pacote]`: Ver informações detalhadas de um pacote

### Sobre yarn dedupe

O comando `yarn dedupe` é utilizado para:

- Remover versões duplicadas de pacotes
- Otimizar a árvore de dependências
- Reduzir o tamanho do node_modules
- Resolver conflitos de versões similares
- Melhorar a performance da aplicação

✅ **Quando Usar**:

- Após adicionar novas dependências
- Quando o node_modules estiver muito grande
- Se houver warnings de versões duplicadas
- Durante otimização de performance
- Antes de fazer deploy em produção

⚠️ **Cuidados**:

- Teste a aplicação após usar dedupe
- Verifique se não houve breaking changes
- Mantenha um backup do yarn.lock
- Execute em ambiente de desenvolvimento primeiro

💡 **Dica**: Use `yarn dedupe --check` para verificar duplicações sem fazer alterações

### ❌ Não Usar

- Evitar comandos npm (npm install, npm run, etc)
- Não manter package-lock.json
- Não misturar npm e yarn no mesmo projeto

## Scripts do Projeto

```bash
yarn dev                  # Ambiente de desenvolvimento
yarn build               # Build de produção
yarn start               # Iniciar em produção
yarn lint                # Executar linter
```

## Arquivos de Lock

- Manter apenas: yarn.lock
- Remover: package-lock.json

## Configuração do .gitignore para Yarn

```plaintext
# Yarn
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
.pnp.*
```

## Instalação no macOS

- Instalado via Homebrew: `brew install yarn`
- Atualização: `brew upgrade yarn`
- Verificar versão: `yarn --version`

## Boas Práticas para macOS

1. **Sempre prefira Homebrew para instalações globais**

   - Mais confiável
   - Melhor gerenciamento de dependências
   - Atualizações mais simples
   - Menos problemas de permissão

2. **Comandos Homebrew Úteis**

   ```bash
   brew install [pacote]    # Instalar pacote
   brew upgrade [pacote]    # Atualizar pacote
   brew uninstall [pacote]  # Remover pacote
   brew doctor             # Verificar problemas
   brew update             # Atualizar Homebrew
   ```

3. **Manutenção**
   - Mantenha o Homebrew atualizado
   - Limpe pacotes antigos periodicamente: `brew cleanup`
   - Verifique dependências: `brew deps --tree [pacote]`

## Configuração do ESLint

### Configuração Recomendada

1. **Instalação das Dependências**

```bash
yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y
```

2. **Arquivo de Configuração Base**

```javascript:eslint.config.mjs
export default {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:jsx-a11y/recommended',
    'next/core-web-vitals',
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  plugins: ['@typescript-eslint', 'react', 'jsx-a11y'],
  rules: {
    // Regras personalizadas
    'react/react-in-jsx-scope': 'off',
    'react/prop-types': 'off',
    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/no-explicit-any': 'warn',
    'no-console': ['warn', { allow: ['warn', 'error'] }],
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
  ignorePatterns: [
    'node_modules/',
    '.next/',
    'out/',
    'public/',
    '*.config.js',
    '*.config.mjs',
  ],
}
```

3. **Scripts no package.json**

```json
{
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx",
    "lint:fix": "eslint . --ext .ts,.tsx --fix"
  }
}
```

### Boas Práticas de Linting

✅ **Recomendado**:

- Execute o linter antes de cada commit
- Configure o auto-fix no seu editor
- Use o ESLint junto com o Prettier
- Mantenha as regras consistentes em todo o projeto
- Documente exceções às regras quando necessário

❌ **Evite**:

- Desabilitar regras do ESLint sem motivo claro
- Ignorar warnings do linter
- Misturar diferentes padrões de código
- Deixar regras conflitantes ativas

### Integração com VSCode

1. **Instale a extensão ESLint**
2. **Configure o settings.json**:

```json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}
```

### Resolução de Problemas Comuns

1. **Conflitos com Prettier**:

   - Instale `eslint-config-prettier`
   - Adicione `prettier` ao final do array `extends`

2. **Regras Muito Restritivas**:

   - Ajuste as regras gradualmente
   - Comece com warnings antes de errors
   - Documente as razões das alterações

3. **Performance**:
   - Use `.eslintignore` para diretórios grandes
   - Configure o cache do ESLint
   - Limite o escopo da análise quando necessário

## Análise de Bundle com yarn analyze

### Configuração do Analisador de Bundle

1. **Instalação da Dependência**

```bash
yarn add -D @next/bundle-analyzer
```

2. **Configuração no next.config.js**

```javascript:next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})

module.exports = withBundleAnalyzer({
  // ... outras configurações do Next.js
})
```

3. **Adicione o Script no package.json**

```json
{
  "scripts": {
    "analyze": "ANALYZE=true yarn build",
    "analyze:win": "set ANALYZE=true && yarn build" // Para Windows
  }
}
```

### Como Usar

1. **Execute o Comando**

```bash
yarn analyze
```

2. **Interpretando os Resultados**:
   - Dois relatórios serão gerados automaticamente no navegador:
     - Client bundles (`.next/analyze/client.html`)
     - Server bundles (`.next/analyze/server.html`)
   - Analise o tamanho dos módulos
   - Identifique dependências pesadas
   - Verifique código não utilizado

### Boas Práticas de Análise

✅ **Recomendado**:

- Execute a análise antes de cada deploy
- Monitore o crescimento do bundle
- Otimize dependências grandes
- Utilize code splitting quando necessário
- Remova imports não utilizados

❌ **Evite**:

- Ignorar bundles muito grandes
- Manter dependências duplicadas
- Importar bibliotecas inteiras quando necessário apenas alguns componentes
- Deixar código morto no bundle

### Otimizações Comuns

1. **Redução de Tamanho**:

   - Use dynamic imports para código não crítico
   - Implemente lazy loading para componentes grandes
   - Remova dependências não utilizadas
   - Utilize versões mais leves de bibliotecas quando possível

2. **Monitoramento**:

   - Compare resultados entre builds
   - Estabeleça limites máximos de tamanho
   - Documente decisões de otimização
   - Mantenha um histórico de análises

3. **Performance**:
   - Priorize otimizações em páginas críticas
   - Balance tamanho vs funcionalidade
   - Considere estratégias de caching
   - Implemente code splitting estratégico

## Autoprefixer e Compatibilidade Cross-Browser

### O que é Autoprefixer?

O Autoprefixer é uma ferramenta essencial que:

- Adiciona automaticamente prefixos de vendor (-webkit-, -moz-, -ms-)
- Garante compatibilidade cross-browser
- Integra-se com Tailwind CSS
- Mantém o código limpo e manutenível

### Por que é Necessário?

1. **Integração com Tailwind CSS**:

   - Trabalha em conjunto com o sistema de estilos
   - Garante que todas as classes funcionem em diferentes navegadores
   - Processa automaticamente as utilidades do Tailwind

2. **Exemplos de Transformação**:

```css
/* Seu CSS original */
.elemento {
  display: flex;
  user-select: none;
  backdrop-filter: blur(10px);
}

/* Após o Autoprefixer */
.elemento {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  -webkit-backdrop-filter: blur(10px);
  backdrop-filter: blur(10px);
}
```

### Configuração no Next.js

1. **Instalação**:

```bash
yarn add -D autoprefixer
```

2. **Configuração (postcss.config.js)**:

```javascript:postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
```

### Boas Práticas

✅ **Recomendado**:

- Mantenha sempre atualizado
- Use em conjunto com Tailwind CSS
- Verifique a cobertura de browsers no browserslist
- Mantenha as configurações padrão quando possível

❌ **Evite**:

- Remover o autoprefixer do projeto
- Adicionar prefixos manualmente
- Sobrescrever configurações padrão sem necessidade
- Ignorar warnings de compatibilidade

### Verificação de Prefixos

Para verificar quais prefixos estão sendo aplicados:

```bash
yarn dlx autoprefixer --info
```

### Integração com Editores

Para VSCode:

- Instale a extensão "PostCSS Language Support"
- Habilite suporte a CSS moderno
- Veja os prefixos sendo aplicados em tempo real

### Resolução de Problemas

1. **Prefixos Não Aplicados**:

   - Verifique se o autoprefixer está listado no postcss.config.js
   - Confirme se o browserslist está configurado corretamente
   - Limpe o cache do Next.js (.next)

2. **Conflitos**:
   - Mantenha todas as dependências CSS atualizadas
   - Verifique a ordem dos plugins no postcss.config.js
   - Evite múltiplas configurações de PostCSS

## Gerenciamento de Dependências Atualizado

### Resolvendo Problemas de Peer Dependencies

1. **Identificação de Problemas**:

   - Use `yarn deps:outdated` para verificar dependências desatualizadas
   - Verifique avisos de peer dependencies com `yarn explain peer-requirements`
   - Monitore warnings do Yarn sobre dependências incorretas

2. **Soluções Aplicadas**:

   - Remova configurações de workspaces não utilizadas
   - Adicione peer dependencies faltantes no package.json
   - Mantenha resolutions para versões específicas
   - Use `yarn dedupe` para otimizar dependências

3. **Estrutura do package.json Otimizada**:

```json
{
  "peerDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "framer-motion": "^10.18.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "tailwind-variants": "^0.3.0",
    "tailwindcss": "^3.4.0"
  },
  "resolutions": {
    "@nextui-org/react": "2.2.9",
    "@nextui-org/system": "2.0.15",
    "@nextui-org/theme": "2.1.17",
    "next": "14.0.4",
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}
```

4. **Processo de Verificação**:

   ```bash
   # 1. Limpar dependências duplicadas
   yarn deps:clean

   # 2. Verificar saúde das dependências
   yarn deps:check

   # 3. Testar a aplicação
   yarn dev
   ```

5. **Tratamento de Avisos**:
   - Avisos do pacote `pacote` podem ser ignorados (dependência interna do Yarn)
   - Mantenha backup do yarn.lock antes de alterações
   - Documente mudanças significativas
   - Teste a aplicação após cada modificação

### Boas Práticas Atualizadas

✅ **Recomendado**:

- Mantenha peer dependencies alinhadas com as dependências principais
- Use resolutions para fixar versões críticas
- Remova configurações não utilizadas
- Monitore regularmente a saúde das dependências

❌ **Evite**:

- Ignorar avisos de peer dependencies
- Manter configurações de workspace sem necessidade
- Misturar diferentes versões de pacotes core
- Deixar dependências conflitantes

### Scripts de Manutenção

```json
{
  "scripts": {
    "deps:outdated": "yarn up -i",
    "deps:clean": "yarn dedupe",
    "deps:check": "yarn dlx @yarnpkg/doctor",
    "validate": "yarn deps:outdated && yarn check-security && yarn lint"
  }
}
```

## Resolução de Problemas de Tipos TypeScript

### Abordagem para Erros de Tipos Persistentes

1. **Quando Aguardar a Resolução Automática**:

   - Se o erro é relacionado a tipos de módulos externos
   - Se você acabou de instalar ou atualizar dependências
   - Se o erro aparece após mudanças no `tsconfig.json`
   - Se o erro persiste mesmo após reiniciar o editor

2. **Tempo de Espera Recomendado**:

   - Aguarde o TypeScript Server reiniciar (geralmente 30 segundos)
   - Deixe o servidor de desenvolvimento rodando (`yarn dev`)
   - Permita que o compositor de tipos do TypeScript trabalhe
   - Evite fazer alterações durante este período

3. **Sinais de Resolução Automática**:
   - Os erros começam a desaparecer sem intervenção
   - O editor mostra menos erros gradualmente
   - As sugestões de autocompletar começam a funcionar
   - O servidor TypeScript mostra "No errors" no log

### ✅ Quando Aguardar:

- Erros de "Cannot find module" após instalação
- Erros de tipos em módulos externos
- Conflitos de tipos após atualização
- Erros que aparecem e desaparecem

### ❌ Quando Intervir:

- Erros em código fonte próprio
- Problemas de sintaxe
- Erros de configuração
- Dependências realmente faltantes

### Boas Práticas

1. **Durante a Espera**:

   - Mantenha o servidor de desenvolvimento rodando
   - Não force reload do TypeScript Server
   - Evite limpar caches desnecessariamente
   - Continue trabalhando em outras partes do código

2. **Após a Resolução**:
   - Documente o tempo necessário para resolução
   - Verifique se todos os tipos estão corretos
   - Faça um commit das alterações que funcionaram
   - Atualize a documentação se necessário

## Erros Comuns de Tipos no TypeScript

### Problemas Frequentes com @types

1. **Módulos Não Encontrados**:

   ```typescript
   // Erro comum
   Não é possível localizar o módulo '[nome-do-pacote]' ou suas declarações de tipo correspondentes.ts(2307)
   ```

   **Soluções**:

   - Aguarde a resolução automática do TypeScript Server
   - Verifique se o pacote @types correspondente está instalado
   - Crie declarações de tipos locais em `src/@types/[nome-do-pacote].d.ts`

2. **Conflitos de Versões**:

   - Tipos incompatíveis entre dependências
   - Versões diferentes do mesmo pacote @types
   - Tipos desatualizados em relação à implementação

3. **Boas Práticas para Tipos**:
   - Mantenha os pacotes @types alinhados com as versões das dependências
   - Prefira tipos oficiais dos pacotes quando disponíveis
   - Use declarações locais apenas quando necessário
   - Documente decisões sobre tipos personalizados

### Estratégias de Resolução

1. **Abordagem Gradual**:

   ```bash
   # 1. Verifique se há tipos oficiais
   yarn add -D @types/[pacote]

   # 2. Se não houver, crie tipos locais
   src/@types/[pacote].d.ts
   ```

2. **Declarações Locais**:

   ```typescript
   // src/@types/[pacote].d.ts
   declare module "[pacote]" {
     // Tipos necessários
     export interface Config {
       // ...
     }
   }
   ```

3. **Configuração do TypeScript**:
   ```json
   {
     "compilerOptions": {
       "typeRoots": ["./node_modules/@types", "./src/@types"]
     }
   }
   ```

### Prevenção de Problemas

1. **Manutenção Regular**:

   - Atualize os pacotes @types regularmente
   - Monitore conflitos de tipos
   - Mantenha documentação de tipos personalizada

2. **Organização**:

   - Mantenha tipos locais em `src/@types/`
   - Use namespaces para evitar conflitos
   - Documente decisões sobre tipos

3. **Quando Criar Tipos Locais**:
   - Pacote não tem tipos oficiais
   - Tipos oficiais estão desatualizados
   - Necessidade de extensão de tipos existentes
   - Resolução temporária de conflitos

### Sinais de Alerta

✅ **Normal**:

- Erros temporários após instalação de pacotes
- Avisos de tipos durante atualizações
- Conflitos resolvidos automaticamente
- Erros que desaparecem após reiniciar o servidor

❌ **Requer Atenção**:

- Erros persistentes após reiniciar
- Conflitos entre versões de tipos
- Tipos incompatíveis entre dependências
- Erros em código fonte próprio

## Erros Persistentes em Arquivos Específicos

### Erros Comuns em page.tsx

1. **Erros de JSX e Tipos Implícitos**:

   ```typescript
   // Erro comum
   O elemento JSX implicitamente tem o tipo 'any' porque não há uma interface de 'JSX.IntrinsicElements'.
   ```

   **Soluções**:

   - Aguarde o TypeScript Server carregar completamente
   - Reinicie o servidor de desenvolvimento
   - Se persistir, adicione tipos explícitos para elementos JSX

2. **Módulos Não Encontrados em Páginas**:

   ```typescript
   // Erro comum
   Não é possível localizar o módulo 'react' ou suas declarações de tipo correspondentes.
   ```

   **Soluções**:

   - Verifique se o arquivo tem a diretiva 'use client'
   - Aguarde a resolução automática
   - Se persistir após 1-2 minutos, tente:
     1. Limpar cache: `rm -rf .next`
     2. Reinstalar deps: `yarn install`
     3. Reiniciar servidor: `yarn dev`

3. **Parâmetros com Tipo 'any' Implícito**:
   ```typescript
   // Erro comum
   O parâmetro 'prev' implicitamente tem um tipo 'any'.
   ```
   **Soluções**:
   - Aguarde a inferência de tipos
   - Se persistir, adicione tipos explícitos:
     ```typescript
     const toggleSidebar = useCallback(() => {
       setIsSidebarOpen((prev: boolean) => !prev);
     }, []);
     ```

### Ordem de Resolução

1. **Primeira Tentativa**:

   - Aguarde 30-60 segundos após iniciar o servidor
   - Não faça alterações durante este período
   - Observe se os erros começam a desaparecer

2. **Segunda Tentativa** (se os erros persistirem):

   ```bash
   # 1. Pare o servidor
   # 2. Limpe os caches
   rm -rf .next
   rm -rf node_modules/.cache
   # 3. Reinstale as dependências
   yarn install
   # 4. Inicie o servidor
   yarn dev
   ```

3. **Terceira Tentativa** (se ainda persistir):
   - Feche completamente o editor
   - Limpe os caches do TypeScript
   - Reabra o projeto
   - Inicie o servidor

### Sinais de Resolução Normal vs. Problemas Reais

✅ **Normal**:

- Erros desaparecem gradualmente
- Erros somem após reiniciar o servidor
- IDE mostra menos erros com o tempo
- Erros de tipos são resolvidos automaticamente

❌ **Problema Real**:

- Erros persistem após múltiplas tentativas
- Erros aumentam com o tempo
- IDE trava ou fica lento
- Build falha com os mesmos erros

### Boas Práticas para Prevenção

1. **Durante o Desenvolvimento**:

   - Mantenha o servidor rodando
   - Evite editar arquivos durante a inicialização
   - Aguarde a resolução automática
   - Use tipos explícitos em casos críticos

2. **Configuração do Projeto**:

   - Mantenha dependências atualizadas
   - Use versões estáveis dos pacotes
   - Evite misturar diferentes versões do mesmo pacote
   - Mantenha o tsconfig.json consistente

3. **Quando Criar Tipos Locais**:
   - Apenas após tentar a resolução automática
   - Quando os erros são consistentes
   - Para componentes específicos do projeto
   - Para sobrescrever tipos problemáticos

## Erros de Lint em page.tsx

### Erros Comuns e Soluções

1. **Erros de Importação**:

   ```typescript
   // Erro comum
   'React' must be in scope when using JSX
   ```

   **Soluções**:

   - Adicione a diretiva 'use client' no topo do arquivo
   - Aguarde o ESLint reconhecer as configurações do Next.js
   - Se persistir, verifique se `eslint-config-next` está instalado

2. **Erros de Tipos em Componentes**:

   ```typescript
   // Erro comum
   Type '{ children: string; }' is not assignable to type 'IntrinsicAttributes'
   ```

   **Soluções**:

   - Aguarde o TypeScript Server carregar os tipos
   - Se persistir, verifique se os tipos do NextUI estão corretos
   - Adicione tipos explícitos quando necessário

3. **Erros de Hook**:
   ```typescript
   // Erro comum
   React Hook useCallback has missing dependencies
   ```
   **Soluções**:
   - Aguarde o ESLint carregar as regras do React
   - Se persistir, adicione as dependências faltantes
   - Use o comando `yarn lint --fix` para correções automáticas

### Ordem de Verificação

1. **Primeira Etapa**:

   ```bash
   # Verifique os erros de lint
   yarn lint
   ```

2. **Segunda Etapa** (se houver erros):

   ```bash
   # Tente correção automática
   yarn lint --fix
   ```

3. **Terceira Etapa** (se persistir):
   - Verifique as regras do ESLint
   - Atualize as dependências do ESLint
   - Limpe o cache do ESLint

### Boas Práticas

1. **Durante o Desenvolvimento**:

   - Mantenha o ESLint atualizado
   - Use o autofix quando possível
   - Documente exceções às regras
   - Mantenha consistência nas soluções

2. **Configuração**:

   - Use as regras recomendadas do Next.js
   - Evite desabilitar regras globalmente
   - Documente regras personalizadas
   - Mantenha o .eslintrc consistente

3. **Quando Ignorar**:
   - Apenas em casos excepcionais
   - Com comentários explicativos
   - Temporariamente durante desenvolvimento
   - Para regras específicas do arquivo

### Prevenção

1. **Setup Inicial**:

   ```json
   // package.json
   {
     "scripts": {
       "lint": "next lint",
       "lint:fix": "next lint --fix"
     }
   }
   ```

2. **Configuração do Editor**:

   ```json
   // .vscode/settings.json
   {
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true
     }
   }
   ```

3. **Hooks do Git**:
   ```bash
   # .husky/pre-commit
   yarn lint
   ```

### Sinais de Alerta

✅ **Normal**:

- Erros resolvidos com --fix
- Warnings de dependências
- Erros temporários após mudanças
- Problemas resolvidos após reload

❌ **Requer Atenção**:

- Erros persistentes após --fix
- Conflitos entre regras
- Erros em múltiplos arquivos
- Problemas de configuração