Installation

Get a new Velox TS project running in under a minute. The create-velox-app scaffolder sets up your database, installs dependencies, and generates a working API you can start building on immediately.

Prerequisites

• Node.js v20 or higher
• pnpm (recommended) or npm/yarn
• A code editor with TypeScript support (VS Code recommended)

Create a New Project

The fastest way to start is with create-velox-app:

npx create-velox-app my-app
cd my-app

pnpm Users: Approve Native Builds

If you’re using pnpm (recommended), you’ll need to approve native module compilation for packages like esbuild, bcrypt, and prisma:

pnpm approve-builds

Select the packages to approve when prompted. This is a one-time setup per project.

Scaffolder Options

The scaffolder will prompt you to choose:

• Template: default, auth, trpc, rsc, or rsc-auth
• Package manager: pnpm, npm, or yarn
• Database: SQLite (default) or PostgreSQL

Project Templates

Template	Use Case
default	REST API with basic CRUD
--auth	JWT authentication, guards, policies
--trpc	tRPC-only (no REST adapter)
--rsc	React Server Components with Vinxi
--rsc-auth	RSC + JWT authentication

# Explicit template selection
npx create-velox-app my-app --auth
npx create-velox-app my-app --rsc

Initialize the Database

After creating your project:

pnpm db:push

The Prisma client is generated automatically via a postinstall hook — no need to run db:generate manually.

Start Development

velox dev

Your API is now running at http://localhost:3030.

Test it:

curl http://localhost:3030/api/health
# {"status":"ok","timestamp":"..."}

If your project includes a frontend (apps/web/), add --all to start both backend and frontend:

velox dev --all

Your frontend is now running at http://localhost:8080.

Adding to an Existing Project

If you want to add Velox TS to an existing project instead of using the scaffolder:

Backend (API)

# Dependencies
pnpm add @veloxts/velox @prisma/client @prisma/adapter-better-sqlite3 \
  @prisma/client-runtime-utils better-sqlite3 dotenv zod

# Dev dependencies
pnpm add -D @veloxts/cli prisma tsx tsup typescript @types/node hot-hook

With authentication:

pnpm add @veloxts/auth bcrypt
pnpm add -D @types/bcrypt

Frontend (SPA Client)

# Dependencies
pnpm add @veloxts/client @tanstack/react-query react react-dom

# Dev dependencies
pnpm add -D @vitejs/plugin-react vite typescript @types/react @types/react-dom

PostgreSQL Instead of SQLite

Replace the SQLite adapter:

pnpm remove @prisma/adapter-better-sqlite3 better-sqlite3
pnpm add @prisma/adapter-pg

Minimal Setup

For the smallest footprint, install individual packages instead of @veloxts/velox:

# Core only (no auth, no ORM helpers)
pnpm add @veloxts/core @veloxts/router @veloxts/validation

Related Content

• Quick Start - Build your first procedure
• Project Structure - Understand the layout