Documentación
Preguntas Frecuentes

❓ Preguntas Frecuentes (FAQ)

Esta sección contiene respuestas a las preguntas más comunes sobre Fox Framework. Si no encuentras la respuesta que buscas, no dudes en consultar nuestra documentación completa o contactar con la comunidad.

🚀 Primeros Pasos

¿Qué es Fox Framework?

Fox Framework es un framework web moderno para TypeScript/Node.js que proporciona una arquitectura escalable y herramientas integradas para desarrollar aplicaciones web robustas. Incluye sistema de routing, motor de templates, CLI, cache, logging y mucho más.

¿Por qué elegir Fox Framework sobre Express?

Fox Framework construye sobre Express pero agrega:

  • Estructura organizada: Arquitectura predefinida y mejores prácticas
  • TypeScript first: Tipado completo y mejor experiencia de desarrollo
  • Herramientas integradas: CLI, cache, logging, validación sin configuración extra
  • Escalabilidad: Patrones de diseño para aplicaciones grandes
  • Monitoreo: Métricas y observabilidad incluidas

¿Fox Framework es compatible con el ecosistema de Express?

Sí, completamente. Fox Framework está construido sobre Express, por lo que puedes usar cualquier middleware, librería o herramienta del ecosistema de Express sin problemas.

¿Qué versión de Node.js necesito?

Fox Framework requiere Node.js 18.0 o superior. Recomendamos usar la versión LTS más reciente para mejor estabilidad y rendimiento.

📦 Instalación y Configuración

¿Cómo instalo Fox Framework?

# Opción 1: Uso directo sin instalación global (recomendado)
npx -p @foxframework/core tsfox new mi-proyecto
cd mi-proyecto
npm install
npm run dev
 
# Opción 2: Instalación global (para usar 'tsfox' directamente)
npm install -g @foxframework/core
tsfox new mi-proyecto
npm install && npm run dev

¿Puedo usar Fox Framework en un proyecto existente?

Sí, instala el paquete core y crea tu instancia:

npm install @foxframework/core
import { FoxFactory } from '@foxframework/core';
 
const app = FoxFactory.createInstance({
  port: 3000,
  routes: './src/routes'
});
 
app.start();

¿Cómo configuro la base de datos?

Fox Framework soporta múltiples bases de datos:

const server = FoxFactory.createServer({
  database: {
    type: 'postgresql', // postgresql, mysql, sqlite, mongodb
    url: 'postgresql://user:pass@localhost:5432/mydb',
    // opciones adicionales
  }
});

🏗️ Arquitectura y Desarrollo

¿Debo seguir una estructura de carpetas específica?

Recomendamos esta estructura, pero es flexible:

src/
├── controllers/     # Lógica de controladores
├── services/       # Lógica de negocio
├── models/         # Modelos de datos
├── middleware/     # Middleware personalizado
├── routes/         # Definición de rutas
├── config/         # Configuración
└── utils/          # Utilidades

¿Cómo manejo la autenticación?

Fox Framework incluye middleware de autenticación:

import { AuthMiddleware } from '@foxframework/auth-jwt';
 
// Configurar JWT
const authConfig = {
  jwt: {
    secret: 'tu-secreto',
    expiresIn: '7d'
  }
};
 
// Usar en rutas
router.get('/protected', AuthMiddleware.jwt(authConfig), controller.method);

¿Puedo usar otros ORMs además del incluido?

Sí, Fox Framework es ORM-agnóstico. Puedes usar:

  • Prisma
  • TypeORM
  • Sequelize
  • Mongoose (para MongoDB)
  • O cualquier otro ORM/ODM

¿Cómo implemento validación de datos?

Fox Framework incluye validación integrada:

import { ValidationMiddleware, Schema } from '@foxframework/validation';
 
const userSchema = Schema.object({
  name: Schema.string().min(2).max(50),
  email: Schema.string().email(),
  age: Schema.number().min(18)
});
 
router.post('/users', 
  ValidationMiddleware.body(userSchema), 
  userController.create
);

🔧 Funcionalidades Específicas

¿Cómo funciona el sistema de cache?

Fox Framework incluye múltiples estrategias de cache:

import { Cache } from '@foxframework/cache';
 
// Cache en memoria
const memoryCache = Cache.memory();
 
// Cache con Redis
const redisCache = Cache.redis({
  url: 'redis://localhost:6379'
});
 
// Uso
await cache.set('key', 'value', 3600); // TTL 1 hora
const value = await cache.get('key');

¿Puedo usar WebSockets?

Sí, Fox Framework soporta WebSockets:

import { SocketController } from '@foxframework/websockets';
 
class ChatController extends SocketController {
  onConnection(socket: Socket) {
    socket.on('message', (data) => {
      this.broadcast('message', data);
    });
  }
}

¿Cómo implemento background jobs?

Usa el sistema de jobs integrado:

import { JobQueue } from '@foxframework/jobs';
 
const emailQueue = new JobQueue('email-queue');
 
// Agregar job
await emailQueue.add('send-welcome-email', {
  userId: 123,
  email: 'user@example.com'
});
 
// Procesar jobs
emailQueue.process('send-welcome-email', async (job) => {
  await emailService.sendWelcomeEmail(job.data);
});

🚢 Despliegue y Producción

¿Cómo despliego mi aplicación?

Actualmente el CLI expone un set inicial centrado en Docker y (experimental) deploy:

# Generar configuración docker
npx -p @foxframework/core tsfox docker init
 
# Construir imagen
npx -p @foxframework/core tsfox docker build
 
# Ejecutar contenedor
npx -p @foxframework/core tsfox docker run --port 3000:3000
 
# Orquestar con docker-compose
npx -p @foxframework/core tsfox docker compose up -d
 
# (Experimental) Deploy
npx -p @foxframework/core tsfox deploy --interactive

Roadmap (no implementado aún en CLI actual): vercel/heroku/aws helpers dedicados.

¿Qué configuraciones necesito para producción?

Configuración mínima para producción:

NODE_ENV=production
DATABASE_URL=tu-url-de-bd
REDIS_URL=tu-url-de-redis
JWT_SECRET=secreto-ultra-seguro
LOG_LEVEL=info

¿Cómo monitoreo mi aplicación?

Fox Framework incluye métricas automáticas:

// Métricas automáticas disponibles en /metrics
- http_requests_total
- http_request_duration_seconds
- nodejs_memory_usage
- database_connections_active
 
// Health check en /health

🐛 Debugging y Troubleshooting

Mi aplicación es lenta, ¿cómo optimizo?

🔗 Error: 404 al ejecutar npx tsfox ...

Si ves un error E404 del registro npm al intentar npx tsfox new:

Causa: El binario tsfox vive dentro del paquete con scope @foxframework/core. Al no existir un paquete sin scope llamado tsfox, npx busca tsfox y obtiene 404.

Soluciones:

# Forma recomendada sin instalación global
npx -p @foxframework/core tsfox new mi-app
 
# O instala globalmente
npm install -g @foxframework/core
tsfox new mi-app

Verifica con:

npx -p @foxframework/core tsfox --version

❌ Comando tsfox no encontrado tras instalación global

  1. Asegura instalación global:
npm ls -g --depth=0 | grep foxframework
  1. Revisa que tu $PATH incluye el global npm bin:
echo "$PATH" | tr ':' '\n' | grep npm
  1. Ubica la ruta de binarios:
npm bin -g
  1. Si no aparece, reinstala:
npm uninstall -g @foxframework/core
npm install -g @foxframework/core

🔐 El generador AI muestra error de API Key

Crear archivo fox-ai.config.json y exportar variable de entorno:

{
  "provider": "openai",
  "model": "gpt-4",
  "temperature": 0.2,
  "maxTokens": 2000,
  "apiKey": "${OPENAI_API_KEY}"
}
export OPENAI_API_KEY="tu-key"

🐳 El comando docker build falla por plataforma

Si necesitas multi-arquitectura:

npx -p @foxframework/core tsfox docker build --platform linux/amd64

Si usas Apple Silicon y apuntas a amd64, considera activar buildx y QEMU.

🐞 ¿Dónde reporto bugs?

  1. Revisa Issues existentes.
  2. Crea un nuevo Issue con:
    • Pasos para reproducir
    • Versión (npx -p @foxframework/core tsfox --version)
    • Logs relevantes
    • Sistema operativo

🧾 ¿Puedo seguir usando los comandos legacy generate:*?

Los comandos legacy (generate:controller, etc.) están obsoletos. Usa:

npx -p @foxframework/core tsfox generate controller Users --crud --service --test
  1. Habilita el profiler:
import { Profiler } from '@foxframework/core';
Profiler.enable();
  1. Verifica queries de BD:
// Habilita logging de queries lentas
database: {
  logging: true,
  slowQueryThreshold: 1000 // ms
}
  1. Optimiza cache:
// Usa cache para datos frecuentes
const cachedData = await cache.remember('users:active', 3600, async () => {
  return await userService.getActiveUsers();
});

¿Cómo debuggeo errores en producción?

  1. Configura logging estructurado:
logging: {
  level: 'info',
  format: 'json',
  transports: ['console', 'file']
}
  1. Usa correlation IDs:
import { CorrelationMiddleware } from '@foxframework/logging';
app.use(CorrelationMiddleware());
  1. Monitorea errores:
import { ErrorTracker } from '@foxframework/monitoring';
ErrorTracker.configure({
  sentry: { dsn: 'tu-sentry-dsn' }
});

Mi aplicación usa mucha memoria, ¿qué hago?

  1. Analiza memory leaks:
fox analyze:memory
  1. Configura límites:
server: {
  maxMemory: '512mb',
  memoryWarningThreshold: 0.8
}
  1. Optimiza cache:
cache: {
  maxMemory: '128mb',
  evictionPolicy: 'allkeys-lru'
}

🔌 Extensibilidad

¿Puedo crear plugins para Fox Framework?

Sí, Fox Framework es altamente extensible:

import { Plugin } from '@foxframework/core';
 
class MiPlugin extends Plugin {
  name = 'mi-plugin';
  version = '1.0.0';
 
  async install(app: FoxApplication) {
    // Lógica de instalación
    app.use(this.middleware);
  }
 
  private middleware = (req, res, next) => {
    // Tu middleware personalizado
    next();
  };
}
 
// Registrar plugin
app.use(new MiPlugin());

¿Cómo extiendo el CLI?

Puedes agregar comandos personalizados:

// commands/mi-comando.ts
import { Command } from '@foxframework/cli';
 
export class MiComando extends Command {
  signature = 'mi-comando {nombre}';
  description = 'Mi comando personalizado';
 
  async handle() {
    const nombre = this.argument('nombre');
    this.info(`Hola ${nombre}!`);
  }
}

¿Puedo usar Fox Framework con GraphQL?

Sí, Fox Framework es compatible con GraphQL:

import { GraphQLModule } from '@foxframework/graphql';
 
const server = FoxFactory.createServer({
  graphql: {
    typeDefs: './schema.graphql',
    resolvers: './resolvers',
    playground: true
  }
});

🔄 Migración

¿Cómo migro desde Express?

La migración es gradual:

  1. Instala Fox Framework
  2. Reemplaza el servidor gradualmente:
// Antes (Express)
const express = require('express');
const app = express();
 
// Después (Fox Framework)
import { FoxFactory } from '@foxframework/core';
const app = FoxFactory.createServer();
  1. Migra rutas una por una
  2. Adopta nuevas funcionalidades gradualmente

¿Puedo usar mis middlewares de Express existentes?

Sí, todos los middlewares de Express son compatibles:

import cors from 'cors';
import morgan from 'morgan';
 
const server = FoxFactory.createServer();
server.use(cors());
server.use(morgan('combined'));

🌟 Mejores Prácticas

¿Cuáles son las mejores prácticas para estructurar mi código?

  1. Separación de responsabilidades:

    • Controllers: Manejo de HTTP
    • Services: Lógica de negocio
    • Repositories: Acceso a datos

  2. Inyección de dependencias:

class UserController {
  constructor(
    private userService: UserService,
    private emailService: EmailService
  ) {}
}
  1. Validación de entrada:
router.post('/users', ValidationMiddleware.body(userSchema), controller.create);

¿Cómo manejo errores de manera consistente?

Usa el manejador de errores global:

import { ErrorHandler } from '@foxframework/core';
 
app.use(ErrorHandler.global({
  // No mostrar stack traces en producción
  showStack: process.env.NODE_ENV === 'development',
  
  // Log todos los errores
  logErrors: true,
  
  // Transformar errores para la API
  transformError: (error) => ({
    message: error.message,
    code: error.code || 'INTERNAL_ERROR'
  })
}));

¿Cómo testseo mi aplicación?

Fox Framework incluye helpers para testing:

import { TestingModule } from '@foxframework/testing';
 
describe('UserController', () => {
  let app: TestApplication;
 
  beforeAll(async () => {
    app = await TestingModule.createTestApp();
  });
 
  it('should create user', async () => {
    const response = await app
      .post('/api/users')
      .send({ name: 'John', email: 'john@example.com' })
      .expect(201);
 
    expect(response.body.success).toBe(true);
  });
});

📚 Recursos Adicionales

¿Dónde encuentro más ejemplos?

¿Cómo contribuyo al framework?

  1. Fork del repositorio
  2. Crea una branch para tu feature
  3. Escribe tests
  4. Envía un Pull Request

Ver Guía de contribución para más detalles.

¿Dónde reporto bugs?

¿Hay soporte comercial disponible?

Sí, ofrecemos diferentes niveles de soporte:

  • Community: Gratis, a través de GitHub y Discord
  • Professional: Soporte por email con SLA
  • Enterprise: Soporte dedicado y consultoría

Contacta con nosotros en support@fox-framework.com

💡 ¿No encontraste tu respuesta?

Si tu pregunta no está aquí:

  1. Busca en la documentación completa
  2. Revisa GitHub Issues (opens in a new tab)
  3. Pregunta en Discord (opens in a new tab)
  4. Crea un nuevo issue en GitHub

¡La comunidad de Fox Framework está aquí para ayudarte!

ChangelogGuía de Migración