create-fluxstack 1.0.2 → 1.0.3

package/ai-context/reference/troubleshooting.md

@@ -0,0 +1,407 @@
+# 🚨 Troubleshooting - FluxStack
+
+> **Guia completo para resolver problemas comuns no FluxStack**
+
+## ⚡ **Diagnóstico Rápido**
+
+### **🔍 Comandos de Diagnóstico**
+```bash
+# 1. Verificar APIs
+curl http://localhost:3000/api/health
+curl http://localhost:3000/swagger/json
+
+# 2. Verificar TypeScript
+bunx tsc --noEmit
+
+# 3. Verificar testes
+bun run test
+
+# 4. Verificar build
+bun run build
+```
+
+### **🌐 URLs Importantes**
+- **Backend**: http://localhost:3000
+- **Frontend**: http://localhost:5173  
+- **Swagger**: http://localhost:3000/swagger
+- **Health**: http://localhost:3000/api/health
+
+## 🔧 **Problemas de Desenvolvimento**
+
+### **❌ Erro: "Cannot find module 'vite/module-runner'"**
+```bash
+# Problema: Vite sendo importado em produção
+# Solução: Verificar env vars e plugins
+export NODE_ENV=development
+bun run dev
+```
+
+### **❌ Types `unknown` no Eden Treaty**
+```typescript
+// ❌ Problema
+const { data, error } = await api.users.get()
+// data é 'unknown' em vez de { users: User[] }
+
+// ✅ Solução: Verificar response schemas
+export const usersRoutes = new Elysia()
+  .get("/", handler, {
+    response: t.Object({
+      users: t.Array(t.Object({
+        id: t.Number(),
+        name: t.String(),
+        email: t.String()
+      }))
+    })
+  })
+```
+
+### **❌ Hot Reload Não Funciona**
+```bash
+# Verificar se Vite já está rodando
+lsof -i :5173  # Mac/Linux
+netstat -ano | findstr :5173  # Windows
+
+# Matar processo se necessário
+pkill -f vite  # Mac/Linux
+taskkill /F /IM node.exe  # Windows
+
+# Reiniciar
+bun run dev
+```
+
+### **❌ Erro de Porta em Uso**
+```bash
+# Verificar processos na porta
+lsof -i :3000  # Backend
+lsof -i :5173  # Frontend
+
+# Matar processo
+kill -9 <PID>
+
+# Ou usar porta diferente
+PORT=3001 bun run dev
+```
+
+### **❌ TypeScript Errors Massivos**
+```bash
+# 1. Limpar cache
+rm -rf node_modules/.cache
+rm -rf dist/
+
+# 2. Reinstalar
+bun install
+
+# 3. Verificar versões
+bunx tsc --version
+bun --version
+
+# 4. Restart TypeScript server (VS Code)
+Ctrl+Shift+P → "TypeScript: Restart TS Server"
+```
+
+## 🌐 **Problemas de API**
+
+### **❌ CORS Errors**
+```javascript
+// ❌ Error: CORS policy blocks request
+// ✅ Normal: API (3000) ≠ Frontend (5173)
+
+// Verificar se API está respondendo
+fetch('http://localhost:3000/api/health')
+  .then(r => r.json())
+  .then(console.log)
+
+// Eden Treaty deveria lidar automaticamente
+```
+
+### **❌ 404 Not Found nas Rotas**
+```typescript
+// ❌ Problema: Rota não encontrada
+// ✅ Verificar prefix e estrutura
+
+// 1. Verificar export das rotas
+export const apiRoutes = new Elysia({ prefix: "/api" })
+  .use(usersRoutes)  // ← Rota precisa estar registrada
+
+// 2. Verificar URL final
+// users routes com prefix "/users" 
+// apiRoutes com prefix "/api"
+// URL final: /api/users
+```
+
+### **❌ Validation Errors**
+```typescript
+// ❌ Body validation failed
+// ✅ Verificar schema da rota
+
+.post("/", handler, {
+  body: t.Object({
+    name: t.String({ minLength: 2 }),  // ← Verificar requisitos
+    email: t.String({ format: "email" })
+  })
+})
+
+// Client request deve corresponder:
+await api.users.post({
+  name: "João",      // ← String com 2+ chars
+  email: "joao@x.com" // ← Email válido
+})
+```
+
+### **❌ Error Handling Não Funciona**
+```typescript
+// ❌ Problema: Errors não tratados
+const { data, error } = await api.users.get()
+
+// ✅ Sempre verificar error primeiro
+if (error) {
+  console.log(`API Error: ${error.status} - ${error.message}`)
+  return
+}
+
+// Agora data é garantidamente válido
+console.log(data.users)
+```
+
+## ⚛️ **Problemas de Frontend**
+
+### **❌ React Hook Warnings**
+```typescript
+// ❌ Warning: Can't perform state update on unmounted component
+
+// ✅ Solução: Cleanup no useEffect
+useEffect(() => {
+  let mounted = true
+  
+  const loadData = async () => {
+    const { data, error } = await api.users.get()
+    if (mounted && !error) {
+      setUsers(data.users)
+    }
+  }
+  
+  loadData()
+  
+  return () => { mounted = false }  // ← Cleanup
+}, [])
+```
+
+### **❌ State Updates Não Refletem**
+```typescript
+// ❌ Problema: State não atualiza após API call
+
+// ✅ Verificar se setState está sendo chamado
+const createUser = async (userData) => {
+  const { data, error } = await api.users.post(userData)
+  
+  if (!error && data.success) {
+    setUsers(prev => [...prev, data.user])  // ← Crucial!
+  }
+}
+```
+
+### **❌ Infinite Re-renders**
+```typescript
+// ❌ Problema: useEffect sem dependencies
+useEffect(() => {
+  loadUsers()  // ← Vai chamar infinitamente
+})
+
+// ✅ Solução: Dependencies corretas
+useEffect(() => {
+  loadUsers()
+}, [])  // ← Empty array = run once
+
+// ✅ Ou use useCallback
+const loadUsers = useCallback(async () => {
+  // ...
+}, [])
+
+useEffect(() => {
+  loadUsers()
+}, [loadUsers])
+```
+
+## 🏗️ **Problemas de Build**
+
+### **❌ Build Failures**
+```bash
+# 1. Verificar imports
+# ❌ Problema comum
+import { api } from '../../lib/eden-api'  # Path relativo
+import type { User } from '../../../shared/types'  # Muitos ../
+
+# ✅ Usar path aliases (tsconfig.json)
+import { api } from '@/lib/eden-api'
+import type { User } from '@/shared/types'
+
+# 2. Verificar exports
+# Cada arquivo deve ter export padrão ou nomeado correto
+```
+
+### **❌ Type Errors na Build**
+```typescript
+// ❌ Problema: Tipos diferentes dev vs build
+// ✅ Verificar tsconfig.json consistency
+
+{
+  "compilerOptions": {
+    "strict": true,
+    "skipLibCheck": false,  // ← Importante para libs
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+### **❌ Asset Loading Problems**
+```typescript
+// ❌ Problema: Assets não carregam em prod
+// ✅ Usar public/ folder
+
+// ❌ Errado
+import logo from '../assets/logo.png'
+
+// ✅ Correto  
+<img src="/logo.png" />  // File em public/logo.png
+```
+
+## 🐳 **Problemas de Docker**
+
+### **❌ Docker Build Falha**
+```dockerfile
+# ❌ Problema: Node modules não copiados
+# ✅ Verificar .dockerignore
+
+# .dockerignore não deve incluir:
+# node_modules/  ← OK, será reinstalado
+# dist/          ← OK, será gerado
+# .env           ← Cuidado: env vars podem ser necessárias
+```
+
+### **❌ Container Não Inicia**
+```bash
+# Verificar logs
+docker logs <container-id>
+
+# Verificar portas
+docker ps
+docker port <container-id>
+
+# Verificar conectividade
+curl http://localhost:3000/api/health
+```
+
+## 🧪 **Problemas de Testing**
+
+### **❌ Tests Falhando**
+```typescript
+// ❌ Problema: API calls em tests
+// ✅ Mock Eden Treaty
+
+// tests/setup.ts
+vi.mock('@/lib/eden-api', () => ({
+  api: {
+    users: {
+      get: vi.fn(),
+      post: vi.fn()
+    }
+  }
+}))
+
+// test.ts
+import { api } from '@/lib/eden-api'
+
+it('should handle users', () => {
+  const mockUsers = [{ id: 1, name: 'Test' }]
+  vi.mocked(api.users.get).mockResolvedValue({
+    data: { users: mockUsers },
+    error: undefined
+  })
+  
+  // Test component...
+})
+```
+
+### **❌ Mock Not Working**
+```typescript
+// ❌ Problema: Mocks não aplicados
+// ✅ Verificar ordem de imports
+
+// ❌ Errado
+import { Component } from './Component'
+import { vi } from 'vitest'
+
+// ✅ Correto
+import { vi } from 'vitest'
+vi.mock('./api')
+import { Component } from './Component'
+```
+
+## 🔧 **Ferramentas de Debug**
+
+### **✅ Browser DevTools**
+```javascript
+// Network tab
+// - Verificar requests/responses
+// - Status codes
+// - Headers CORS
+
+// Console
+// - Eden Treaty debug
+console.log('API call:', await api.users.get())
+
+// React DevTools  
+// - Component state
+// - Props debugging
+// - Hook values
+```
+
+### **✅ Bun Debugging**
+```bash
+# Debug mode
+DEBUG=* bun run dev
+
+# Verbose output
+bun run dev --verbose
+
+# Memory usage
+bun run --inspect dev
+```
+
+### **✅ Elysia Debugging**
+```typescript
+// app/server/index.ts
+app.onError((error) => {
+  console.error('Elysia Error:', error)
+  return { error: error.message, status: 500 }
+})
+
+app.onRequest((request) => {
+  console.log(`${request.method} ${request.url}`)
+})
+
+app.onResponse((response) => {
+  console.log(`Response: ${response.status}`)
+})
+```
+
+## 📋 **Checklist de Troubleshooting**
+
+### **🔍 Quando algo não funciona:**
+1. **Verificar URLs** - APIs nas portas certas?
+2. **Verificar types** - `bunx tsc --noEmit`
+3. **Verificar console** - Errors no browser/terminal?
+4. **Verificar schemas** - Response schemas definidos?
+5. **Verificar imports** - Paths corretos?
+6. **Reiniciar tudo** - `bun run dev` fresh
+
+### **🆘 Quando tudo falha:**
+1. **Clean install**: `rm -rf node_modules && bun install`
+2. **Clear cache**: `rm -rf dist/ .cache/`
+3. **Restart editor**: Recarregar VS Code
+4. **Check docs**: Verificar esta documentação
+5. **Minimal repro**: Isolar o problema
+
+---
+
+**🎯 90% dos problemas são resolvidos verificando response schemas, imports corretos e reiniciando o dev server!**

package/app/client/README.md

@@ -0,0 +1,69 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      ...tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      ...tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      ...tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

package/app/client/frontend-only.ts

@@ -0,0 +1,12 @@
+// Frontend standalone entry point
+import { startFrontendOnly } from "../../core/client/standalone"
+
+// Configuração para frontend standalone
+const frontendConfig = {
+  clientPath: "app/client",
+  vitePort: (globalThis as any).process?.env?.FRONTEND_PORT || 5173,
+  apiUrl: (globalThis as any).process?.env?.API_URL || "http://localhost:3001"
+}
+
+// Iniciar apenas o frontend
+startFrontendOnly(frontendConfig)

package/app/client/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React + TS</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/app/client/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>