create-fluxstack 1.0.2 → 1.0.3

package/ai-context/reference/environment-vars.md

@@ -0,0 +1,384 @@
+# 🌐 Environment Variables - FluxStack
+
+> **Guia completo de variáveis de ambiente**: configuração, precedência e testing
+
+## 🎯 **Sistema de Environment Variables**
+
+O FluxStack utiliza um **sistema dinâmico** de environment variables com precedência clara e validação automática.
+
+### **📋 Precedência (Maior → Menor)**
+1. **Process env** (`process.env.VAR`)
+2. **Runtime vars** (definidas em runtime)
+3. **`.env` file** (carregado automaticamente)
+4. **Default values** (valores padrão)
+
+## 🔧 **Variáveis Principais**
+
+### **🚀 Servidor (Backend)**
+```bash
+# Porta do servidor
+PORT=3000                    # Default: 3000
+
+# Ambiente de execução
+NODE_ENV=development         # Options: development, production, test
+
+# Host/endereço
+HOST=localhost               # Default: localhost
+API_PREFIX=/api              # Default: /api
+
+# Database (quando configurado)
+DATABASE_URL=postgresql://...
+REDIS_URL=redis://...
+
+# Secrets
+JWT_SECRET=your-secret-here
+API_KEY=your-api-key
+```
+
+### **⚛️ Frontend (Client)**
+```bash
+# Vite variables (VITE_ prefix obrigatório)
+VITE_API_URL=http://localhost:3000
+VITE_APP_NAME=FluxStack
+VITE_APP_VERSION=1.5.0
+VITE_NODE_ENV=development
+
+# Build-specific
+VITE_BUILD_TARGET=browser
+VITE_BASE_URL=/
+```
+
+### **🧪 Testing**
+```bash
+# Test environment
+NODE_ENV=test
+TEST_PORT=3001
+TEST_DB_URL=sqlite::memory:
+
+# Test flags
+SKIP_AUTH_TESTS=false
+MOCK_EXTERNAL_APIS=true
+```
+
+### **🐳 Docker**
+```bash
+# Docker-specific
+DOCKERFILE_TARGET=production
+DOCKER_PORT=3000
+DOCKER_ENV=production
+
+# Multi-stage build
+BUILD_STAGE=build
+RUN_STAGE=runtime
+```
+
+## 📁 **Arquivo .env**
+
+### **📝 Exemplo Completo (.env)**
+```bash
+# ===========================================
+# FluxStack Environment Configuration
+# ===========================================
+
+# Server Configuration
+PORT=3000
+HOST=localhost
+NODE_ENV=development
+API_PREFIX=/api
+
+# Frontend Configuration (Vite)
+VITE_API_URL=http://localhost:3000
+VITE_APP_NAME="FluxStack Development"
+VITE_APP_VERSION=1.5.0
+VITE_NODE_ENV=development
+
+# Development Tools
+DEBUG=true
+LOG_LEVEL=info
+HOT_RELOAD=true
+
+# Database (example - configure as needed)
+# DATABASE_URL=postgresql://user:pass@localhost:5432/fluxstack
+# REDIS_URL=redis://localhost:6379
+
+# Security (NEVER commit real secrets!)
+# JWT_SECRET=your-super-secret-key-here-min-32-chars
+# API_KEY=your-api-key-here
+
+# Testing
+TEST_DATABASE_URL=sqlite::memory:
+MOCK_APIS=true
+
+# Build Configuration
+BUILD_TARGET=development
+OPTIMIZE_BUNDLE=false
+SOURCE_MAPS=true
+```
+
+### **📝 Produção (.env.production)**
+```bash
+# Production Environment
+NODE_ENV=production
+PORT=3000
+HOST=0.0.0.0
+
+# Security
+JWT_SECRET=${JWT_SECRET}  # From environment
+API_KEY=${API_KEY}        # From environment
+
+# Performance  
+OPTIMIZE_BUNDLE=true
+SOURCE_MAPS=false
+LOG_LEVEL=warn
+
+# Database
+DATABASE_URL=${DATABASE_URL}
+REDIS_URL=${REDIS_URL}
+
+# Frontend
+VITE_API_URL=https://api.yourapp.com
+VITE_APP_NAME="FluxStack"
+VITE_NODE_ENV=production
+```
+
+## 🔍 **Validação e Testing**
+
+### **✅ Verificar Environment Variables**
+```bash
+# Comando built-in
+bun run env-test
+
+# Manual check
+curl http://localhost:3000/api/env-test
+```
+
+### **✅ Testing Script**
+```bash
+# Script de teste (run-env-tests.ts)
+#!/usr/bin/env bun
+
+import { env } from 'bun'
+
+console.log('🧪 Environment Variables Test')
+console.log('============================')
+
+// Test server vars
+console.log(`PORT: ${env.PORT || 'undefined'}`)
+console.log(`NODE_ENV: ${env.NODE_ENV || 'undefined'}`)
+console.log(`HOST: ${env.HOST || 'undefined'}`)
+
+// Test frontend vars  
+console.log(`VITE_API_URL: ${env.VITE_API_URL || 'undefined'}`)
+console.log(`VITE_APP_NAME: ${env.VITE_APP_NAME || 'undefined'}`)
+
+// Test precedence
+env.TEST_VAR = 'runtime-value'
+console.log(`Runtime test: ${env.TEST_VAR}`)
+```
+
+## 🛠️ **Configuração por Ambiente**
+
+### **🔧 Development**
+```bash
+# .env.development
+NODE_ENV=development
+DEBUG=true
+HOT_RELOAD=true
+LOG_LEVEL=debug
+
+# Frontend dev
+VITE_API_URL=http://localhost:3000
+VITE_APP_NAME="FluxStack [DEV]"
+```
+
+### **🧪 Testing**
+```bash
+# .env.test
+NODE_ENV=test
+PORT=3001
+LOG_LEVEL=silent
+
+# Test database
+TEST_DATABASE_URL=sqlite::memory:
+MOCK_EXTERNAL_APIS=true
+
+# Frontend test
+VITE_API_URL=http://localhost:3001
+```
+
+### **🚀 Production**
+```bash
+# .env.production
+NODE_ENV=production
+LOG_LEVEL=info
+OPTIMIZE_BUNDLE=true
+
+# Security - use real environment vars
+JWT_SECRET=${JWT_SECRET}
+API_KEY=${API_KEY}
+DATABASE_URL=${DATABASE_URL}
+```
+
+## 📊 **Sistema Dinâmico**
+
+### **🔄 Runtime Configuration**
+```typescript
+// core/config/env-dynamic.ts
+export class DynamicEnvConfig {
+  static setEnvironment(env: 'development' | 'production' | 'test') {
+    process.env.NODE_ENV = env
+    // Reconfigure based on environment
+    this.loadEnvironmentSpecificConfig()
+  }
+
+  static override(key: string, value: string) {
+    process.env[key] = value
+    console.log(`Environment override: ${key}=${value}`)
+  }
+}
+```
+
+### **✅ Precedência em Ação**
+```bash
+# 1. .env file
+PORT=3000
+
+# 2. Runtime override
+DynamicEnvConfig.override('PORT', '4000')
+
+# 3. Process env (highest priority)
+PORT=5000 bun run dev
+
+# Result: PORT=5000 (process env wins)
+```
+
+## 🚨 **Security Best Practices**
+
+### **🔒 Secrets Management**
+```bash
+# ❌ NUNCA committar secrets
+JWT_SECRET=actual-secret-here  # ❌ NO!
+
+# ✅ Use placeholders no .env  
+JWT_SECRET=${JWT_SECRET}       # ✅ YES!
+
+# ✅ Set real values via environment
+export JWT_SECRET="actual-secret"
+bun run start
+```
+
+### **🛡️ Validation**
+```typescript
+// Validate required vars
+const requiredVars = ['DATABASE_URL', 'JWT_SECRET']
+
+for (const varName of requiredVars) {
+  if (!process.env[varName]) {
+    throw new Error(`Required environment variable missing: ${varName}`)
+  }
+}
+```
+
+### **🔍 Environment Detection**
+```typescript
+export const isProduction = process.env.NODE_ENV === 'production'
+export const isDevelopment = process.env.NODE_ENV === 'development'
+export const isTest = process.env.NODE_ENV === 'test'
+
+// Use guards
+if (isProduction) {
+  // Production-only code
+  app.use(helmet())
+}
+
+if (isDevelopment) {
+  // Development-only code
+  app.use(cors({ origin: 'http://localhost:5173' }))
+}
+```
+
+## 🐳 **Docker Environment**
+
+### **📦 Dockerfile ENV**
+```dockerfile
+# Build args
+ARG NODE_ENV=production
+ARG API_URL=http://localhost:3000
+
+# Runtime env
+ENV NODE_ENV=${NODE_ENV}
+ENV PORT=3000
+ENV HOST=0.0.0.0
+
+# Frontend build vars
+ENV VITE_API_URL=${API_URL}
+ENV VITE_NODE_ENV=${NODE_ENV}
+```
+
+### **🚀 Docker Compose**
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build: .
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - DATABASE_URL=${DATABASE_URL}
+      - JWT_SECRET=${JWT_SECRET}
+    env_file:
+      - .env.production
+```
+
+## 📋 **Troubleshooting**
+
+### **🔍 Debug Environment**
+```typescript
+// Debug current environment
+console.log('Environment Debug:', {
+  NODE_ENV: process.env.NODE_ENV,
+  PORT: process.env.PORT,
+  all_env: Object.keys(process.env).filter(k => k.startsWith('VITE_'))
+})
+```
+
+### **⚠️ Problemas Comuns**
+
+#### **1. Frontend Vars Não Carregam**
+```bash
+# ❌ Problema: Var sem VITE_ prefix
+API_URL=http://localhost:3000  # Não funciona no frontend
+
+# ✅ Solução: Usar VITE_ prefix
+VITE_API_URL=http://localhost:3000  # Funciona!
+```
+
+#### **2. Env File Não Carregado**
+```bash
+# Verificar se .env existe no root
+ls -la .env
+
+# Verificar conteúdo
+cat .env | grep -v '^#'
+
+# Forçar reload
+rm .env && cp .env.example .env
+```
+
+#### **3. Docker Env Não Funciona**
+```dockerfile
+# ❌ Problema: ENV muito cedo
+ENV VITE_API_URL=http://localhost:3000
+COPY . .
+RUN bun run build  # Vite já buildou com localhost
+
+# ✅ Solução: ENV antes do build
+ARG API_URL=http://localhost:3000
+ENV VITE_API_URL=${API_URL}
+COPY . .
+RUN bun run build  # Vite builda com ARG correto
+```
+
+---
+
+**🎯 Sistema de environment variables bem configurado é fundamental para deployment seguro e flexível do FluxStack!**