Configuration

Velox TS handles configuration through environment variables and configuration objects, with optional environment-aware presets that adapt to your NODE_ENV automatically.

Environment-Aware Presets

For production-ready configuration with sensible defaults, use getServerConfig() and usePresets() instead of manual configuration.

Environment Variables

Create a .env file:

# Database
DATABASE_URL="file:./dev.db"

# Auth (if using @veloxts/auth)
JWT_SECRET="your-secret-key-min-32-chars"
JWT_REFRESH_SECRET="your-refresh-secret-min-32-chars"

See Environment Variables Reference for the complete list.

Server Configuration

Recommended: Environment-Aware Config

import { veloxApp, getServerConfig } from '@veloxts/velox';

// Auto-configures port, host, logger based on NODE_ENV
const app = await veloxApp(getServerConfig());

Manual Configuration

import { veloxApp } from '@veloxts/velox';

const app = await veloxApp({
  port: 3030,
  host: 'localhost',
  logger: true,  // or { level: 'debug' } for verbose logging
});

Plugin Configuration

Database Plugin

The database plugin requires a pre-instantiated Prisma client:

import { databasePlugin } from '@veloxts/orm';
import { db } from './config/database.js';  // Your PrismaClient instance

await app.register(databasePlugin({ client: db }));

Auth Plugin

The auth plugin requires JWT configuration nested under jwt:

import { authPlugin } from '@veloxts/auth';

await app.register(authPlugin({
  jwt: {
    secret: process.env.JWT_SECRET!,
    refreshSecret: process.env.JWT_REFRESH_SECRET,
    accessTokenExpiry: '15m',
    refreshTokenExpiry: '7d',
  },
  userLoader: async (userId) => {
    // Fetch user from database - only returned fields are on ctx.user
    const user = await db.user.findUnique({ where: { id: userId } });
    if (!user) return null;
    return { id: user.id, email: user.email, name: user.name };
  },
  rateLimit: {
    max: 100,
    windowMs: 60000,
  },
}));

Or use environment-aware auth presets:

import { getAuthPreset } from '@veloxts/velox';

const authPreset = getAuthPreset();
await app.register(authPlugin({
  jwt: {
    secret: process.env.JWT_SECRET!,
    refreshSecret: process.env.JWT_REFRESH_SECRET,
    ...authPreset.jwt,  // Environment-aware expiry times
  },
  userLoader,
  rateLimit: authPreset.rateLimit,
}));

Prisma Configuration

Prisma 7 requires prisma.config.ts (database URL is configured here, NOT in schema.prisma):

import 'dotenv/config';
import { defineConfig } from 'prisma/config';

export default defineConfig({
  schema: './prisma/schema.prisma',
  datasource: {
    url: process.env.DATABASE_URL,
  },
});

Create your Prisma client with a driver adapter:

// SQLite
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from '@prisma/client';

const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL });
export const db = new PrismaClient({ adapter });

// PostgreSQL
import { PrismaPg } from '@prisma/adapter-pg';

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
export const db = new PrismaClient({ adapter });

Related Content

• Environment Configuration - Presets and security validation
• Environment Variables - Full reference
• Deployment - Production config