Introduction
Velox TS (pronounced Velox TypeScript) is a full-stack TypeScript framework that gives you end-to-end type safety — from database to frontend — without code generation. Define your API once as a procedure, and Velox TS infers types instantly, generates REST endpoints from naming conventions, and exposes tRPC for internal calls. All built on Fastify, Prisma, and Zod.
Philosophy
Section titled “Philosophy”Velox TS is built on four core principles:
-
Type Safety Without Code Generation - types flow through direct imports. No build-time code generation required.
-
Hybrid API Architecture - A single procedure definition serves both tRPC (for type-safe internal calls) and REST (for external API consumers).
-
Convention Over Configuration - Sensible defaults with escape hatches. Naming conventions automatically generate routes.
-
Opinionated & Productive - Expressive syntax, batteries included, progressive disclosure of complexity.
Core Packages
Section titled “Core Packages”| Package | Description |
|---|---|
| @veloxts/core | Fastify wrapper, definePlugin() system, VeloxError hierarchy with fail() API |
| @veloxts/router | Procedure-based API — tRPC + auto-generated REST from naming conventions, OpenAPI/Swagger generation, resourceSchema() for role-based field projection |
| @veloxts/validation | Zod 4 integration — type inference, z.toJSONSchema() for OpenAPI, pagination schemas, query param helpers (queryInt(), queryBoolean(), queryEnum()) |
| @veloxts/orm | Prisma 7 wrapper — driver adapters, schema-driven migrations, type-safe queries |
| @veloxts/auth | JWT (access + refresh tokens), session auth (HMAC-signed, sliding expiration), guards (authenticated, hasRole(), hasPermission(), combinators), policies, CSRF, rate limiting with backoff, HIBP breach checking |
| @veloxts/client | Type-safe frontend API client — types inferred directly from procedure definitions, zero codegen |
| @veloxts/cli | Dev server with HMR, code generators (velox make, velox sync), migrations, OpenAPI CLI, MCP server, introspection |
| @veloxts/web | React Server Components with Vinxi + React 19, file-based routing, validated() server actions with schema validation, useAction() / useFormAction() hooks |
Ecosystem Packages
Section titled “Ecosystem Packages”| Package | Description |
|---|---|
| @veloxts/cache | Multi-driver caching (memory LRU, Redis) — remember(), tag-based invalidation, distributed locks |
| @veloxts/queue | Background job processing (sync, BullMQ) — type-safe jobs with Zod schemas, retry with backoff |
| @veloxts/mail | Email sending (SMTP, Resend, Log driver) — React Email templates, bulk send |
| @veloxts/storage | File storage abstraction (local, S3/R2/MinIO) — signed URLs, streaming, MIME detection |
| @veloxts/scheduler | Cron task scheduling — fluent API, timezone support, overlap prevention |
| @veloxts/events | Real-time broadcasting (WebSocket, SSE) — public/private/presence channels, Redis pub/sub |
| @veloxts/mcp | Model Context Protocol server — AI tool integration for project introspection, code generation, and guidance |
Feature Overview
Section titled “Feature Overview”Routing and API
Section titled “Routing and API”| Feature | How It Works |
|---|---|
| Procedure Definition | procedure().input().query() fluent builder |
| Dual Protocol | Single procedure serves both tRPC and REST |
| REST Generation | Automatic from naming conventions — getUser becomes GET /users/:id |
| OpenAPI/Swagger | Auto-generated spec + CLI + Swagger UI plugin |
| Type-Safe Client | createClient<T>() — types inferred from procedures |
| Resource API | resourceSchema() with role-based field projection (public, authenticated, admin) |
| Rate Limiting | Built-in per-route limiter |
Database
Section titled “Database”| Feature | How It Works |
|---|---|
| ORM | Prisma 7 (Data Mapper pattern) |
| Schema | Prisma Schema Language (.prisma) |
| Migrations | Schema-driven via Prisma Migrate |
| Type Safety | Fully auto-generated from schema |
| Relationships | Schema-defined, queried via include/select |
Authentication and Authorization
Section titled “Authentication and Authorization”| Feature | How It Works |
|---|---|
| JWT Auth | Access + refresh tokens with token store |
| Session Auth | HMAC-signed cookies, sliding expiration |
| Guards | authenticated, hasRole(), hasPermission(), combinators (allOf, anyOf, not) |
| Tagged Resource Views | .output(Schema.authenticated) — auto-projects resource fields by access level |
| Policies | definePolicy() with fluent builder, can() / authorize() |
| CSRF | csrfManager() with timing-safe comparison |
| Password Policy | passwordPolicy() with HIBP breach checking |
| Auth Adapters | JWT (built-in), BetterAuth, Clerk, Auth0 — pluggable via createAuthAdapterPlugin() |
Frontend
Section titled “Frontend”| Feature | How It Works |
|---|---|
| Server Rendering | React Server Components (Vinxi + React 19) |
| SPA | Vite + TanStack Router |
| File-Based Routing | app/pages/ directory (RSC mode) |
| Server Actions | validated() wrapper with schema validation, rate limiting, CSRF |
| Action Hooks | useAction(), useFormAction() for React |
Developer Tooling
Section titled “Developer Tooling”| Feature | How It Works |
|---|---|
| Dev Server | velox dev with HMR, timing metrics, debug mode |
| Schema Sync | velox sync — generate schemas + procedures for all Prisma models |
| Code Generators | velox make resource/namespace/procedure/schema |
| Migrations | velox migrate — status, run, rollback, fresh, reset |
| OpenAPI CLI | velox openapi generate/serve |
| Introspection | velox introspect — list procedures, routes |
| Scaffolder | create-velox-app — 5 templates, 2 databases, 3 package managers |
| MCP Server | velox mcp start — AI-assisted development via Claude |
Two Architectures, One Framework
Section titled “Two Architectures, One Framework”Velox TS gives you a real architectural choice upfront. Both paths share the same backend foundation—procedures, validation, database patterns—but differ in how your web app is rendered and where it lives. One runs entirely in the browser, the other leverages React Server Components for server-side rendering. Pick the approach that fits your project:
API + SPA (Simpler)
Section titled “API + SPA (Simpler)”A classic architecture with a Fastify backend and a separate React SPA frontend. The backend handles API logic, the frontend is a standard Vite-powered Single Page Application. Great for teams with separate frontend/backend concerns or when integrating with existing React apps.
Templates: default, --auth, --trpc
API + RSC (React Server Components)
Section titled “API + RSC (React Server Components)”A unified architecture using Vinxi and React Server Components. Server actions bridge directly to your procedures, enabling seamless data fetching without client-side API calls. Ideal for solo developers or teams wanting server-side rendering and a tighter integration between UI and data.
Templates: --rsc, --rsc-auth
Both approaches share the same backend patterns (procedures, validation, database) - only the frontend architecture differs.
Who Is This For?
Section titled “Who Is This For?”- Full-stack TypeScript developers
- Solo developers building complete applications
- Teams requiring type-safety across the entire stack
- Developers who appreciate elegant, expressive APIs
Related Content
Section titled “Related Content”- Installation - Set up your first project
- Quick Start - Build your first API
- Templates - Choose your starting point