🦊 Fox Framework

Fox Framework is a TypeScript-first, production-ready web framework for Node.js that combines classic backend patterns (routing, middleware, caching, security) with AI-native capabilities: LLM agents, tool libraries, SSE streaming, and OpenTelemetry tracing — all in one package.

Node.js ≥ 18 · TypeScript 5.x · Express under the hood · Modular by design

🚀 Quick Start

npm install @foxframework/core

Scaffold a new project

npx @foxframework/cli new my-app
cd my-app
npm install
npm run dev

Minimal server

import { FoxFactory, RequestMethod } from '@foxframework/core';

const app = FoxFactory.create({
  port: 3000,
  env: 'development',
  requests: [
    {
      path: '/',
      method: RequestMethod.GET,
      handler: (_req, res) => res.json({ message: 'Hello Fox!' })
    }
  ]
});

app.listen(3000, () => console.log('Ready on http://localhost:3000'));

✨ Features

🧠 AI Agents (v1.4+)

• ReAct agent loop with tool-use, memory, and step iteration
• 6 built-in tools: HTTP, Filesystem, Calculator, JSONPath, SQL Query, Vector Search
• SSE streaming — server-sent events for real-time agent output (text/event-stream)
• OpenTelemetry tracing — spans per agent run and per tool call, with @foxframework/otel-agents bridge
• Model provider packages: OpenAI, Anthropic, Ollama (bring your own API key)

🏗️ Core Framework

• TypeScript-first — full type safety, auto-completion, and .d.ts declarations
• Factory-pattern routing — declarative route definitions with FoxFactory.create()
• Template engine — Handlebars integration with layout support
• Middleware pipeline — async middleware with built-in logging, auth, CSRF, rate limiting

🔒 Security

• JWT, Basic Auth, API Key, and session-based authentication
• Role-based authorization (RBAC)
• CSRF protection, security headers, and rate limiting

📊 Observability

• Structured logging with console, file, and HTTP transports
• Prometheus-format metrics collection
• Health check endpoints and request tracing

🗄️ Data & Caching

• Database abstraction layer with 8 providers (Postgres, MySQL, SQLite, Mongo, Redis, DynamoDB, RDS, DocumentDB)
• Multi-provider caching (Memory, Redis, File) with eviction policies

🚀 DevOps

• Docker multi-stage builds and Docker Compose
• GitHub Actions CI/CD workflows
• Kubernetes deployment manifests

📖 Usage Examples

REST API

import { FoxFactory, RequestMethod } from '@foxframework/core';

const app = FoxFactory.create({
  port: 3000,
  env: 'development',
  requests: [
    { path: '/users',     method: RequestMethod.GET,    handler: getAllUsers },
    { path: '/users',     method: RequestMethod.POST,   handler: createUser },
    { path: '/users/:id', method: RequestMethod.GET,    handler: getUser },
    { path: '/users/:id', method: RequestMethod.PUT,    handler: updateUser },
    { path: '/users/:id', method: RequestMethod.DELETE, handler: deleteUser }
  ]
});

app.listen(3000);

With Middleware

import { FoxFactory, RequestMethod, RequestLoggingMiddleware, AuthMiddleware } from '@foxframework/core';

const app = FoxFactory.create({
  port: 3000,
  env: 'development',
  middlewares: [
    RequestLoggingMiddleware.create(),
    AuthMiddleware.jwt({ secret: process.env.JWT_SECRET || 'dev-secret' })
  ],
  requests: [
    { path: '/protected', method: RequestMethod.GET, handler: protectedRoute }
  ]
});

app.listen(3000);

🧠 AI Agents

import { FoxFactory } from '@foxframework/core';
// Use any model provider package
// import { OpenAiProvider } from '@foxframework/model-openai';

const app = FoxFactory.create({
  port: 3000,
  agents: {
    default: {
      provider: /* your LLM provider instance */,
      tools: [/* HttpTool, FilesystemTool, CalculatorTool, ... */],
      memory: { type: 'buffer', maxTokens: 4096 }
    }
  }
});

app.listen(3000);

🛠️ CLI

The CLI has been extracted to its own package @foxframework/cli:

# Scaffold a project
npx @foxframework/cli new <project-name>

# Generate components
npx @foxframework/cli generate controller users
npx @foxframework/cli generate service auth
npx @foxframework/cli generate middleware validation

🧪 Testing

Fox Framework works with any test runner. Use supertest for HTTP-level integration tests:

import request from 'supertest';
import { FoxFactory, RequestMethod } from '@foxframework/core';

const app = FoxFactory.create({
  port: 0,
  env: 'test',
  requests: [
    { path: '/health', method: RequestMethod.GET, handler: (_, res) => res.json({ ok: true }) }
  ]
});

const server = app.listen(0);

describe('API', () => {
  it('returns health', async () => {
    const res = await request(server).get('/health');
    expect(res.status).toBe(200);
    expect(res.body).toEqual({ ok: true });
  });
});

📦 Ecosystem

Core

| Package | Description | |---|---| | @foxframework/core | Framework core: routing, middleware, logging, caching, security, agents | | @foxframework/cli | Project scaffolding and code generation |

AI & Agents

| Package | Description | |---|---| | @foxframework/model-openai | OpenAI / Azure OpenAI provider | | @foxframework/model-anthropic | Anthropic Claude provider | | @foxframework/model-ollama | Ollama local model provider | | @foxframework/otel-agents | OpenTelemetry tracing bridge for agents |

Vector Stores

| Package | Description | |---|---| | @foxframework/vector-pinecone | Pinecone vector DB provider | | @foxframework/vector-weaviate | Weaviate vector DB provider | | @foxframework/vector-chroma | ChromaDB vector store provider |

Database Providers

| Package | Database | Driver | |---|---|---| | @foxframework/db-postgres | PostgreSQL | pg | | @foxframework/db-mysql | MySQL / MariaDB | mysql2 | | @foxframework/db-sqlite | SQLite | better-sqlite3 | | @foxframework/db-mongo | MongoDB | mongodb | | @foxframework/db-redis | Redis | ioredis | | @foxframework/db-dynamodb | AWS DynamoDB | @aws-sdk/client-dynamodb | | @foxframework/db-rds | AWS RDS / Aurora | pg | | @foxframework/db-documentdb | AWS DocumentDB | mongodb |

Auth

| Package | Description | |---|---| | @foxframework/auth-jwt | JSON Web Token authentication | | @foxframework/auth-oauth | OAuth 2.0 / OpenID Connect | | @foxframework/auth-2fa | Two-factor authentication (TOTP) | | @foxframework/auth-firebase | Firebase Authentication | | @foxframework/auth-cognito | AWS Cognito | | @foxframework/auth-ldap | LDAP / Active Directory |

Serverless

| Package | Description | |---|---| | @foxframework/serverless | AWS Lambda / API Gateway adapter |

All providers implement shared interfaces (IDbProvider, IRepository, IVectorSearchProvider, etc.) exported from @foxframework/core.

🤝 Contributing

See CONTRIBUTING.md.

git clone https://github.com/lnavarrocarter/fox-framework.git
cd fox-framework
npm install
npm run dev

npm test               # All tests
npm run test:unit      # Unit tests
npm run test:integration  # Integration tests
npm run test:coverage  # With coverage

📄 License

MIT © Luis Navarro Carter

🔗 Links

• 📦 NPM Package
• 🐛 Issues
• 💬 Discussions
• 📚 Docs