# 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
