Configuration Reference

This page lists every configuration option available in Velox TS — from server settings and logging to ecosystem package options. For most applications, the environment-aware presets handle this automatically; use this reference when you need fine-grained control.

Environment-Aware Configuration

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

Application Configuration

Recommended: Environment-Aware Config

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

// Auto-configure server based on NODE_ENV
const app = await veloxApp(getServerConfig());

// Auto-configure ecosystem packages (cache, queue, mail, etc.)
await usePresets(app);

await app.start();

See Environment Configuration for full details on presets.

Manual Configuration

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

const app = veloxApp({
  // Server options
  port: 3030,
  host: '0.0.0.0',

  // Logging
  logger: {
    level: 'info', // 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
    transport: {
      target: 'pino-pretty',
    },
  },

  // CORS
  cors: {
    origin: ['http://localhost:3000'],
    credentials: true,
  },
});

Router Configuration

Unified API Registration (Recommended)

The serve() function registers both REST and tRPC endpoints from your procedures:

import { serve } from '@veloxts/router';

// Register both REST (/api) and tRPC (/trpc) with defaults
const router = await serve(app, [healthProcedures, userProcedures] as const);
export type AppRouter = typeof router;

// Custom prefixes
const router = await serve(app, [healthProcedures, userProcedures] as const, {
  api: '/v1',     // REST prefix (default: '/api', or false to disable)
  rpc: '/trpc',   // tRPC prefix (default: '/trpc', or false to disable)
});

// REST only (external API)
await serve(app, [healthProcedures, userProcedures] as const, { rpc: false });

// tRPC only (internal app)
const router = await serve(app, [healthProcedures, userProcedures] as const, { api: false });

Router Helper

The createRouter() helper combines procedure collections into a typed router object:

import { createRouter, extractRoutes } from '@veloxts/router';

// Returns { collections, router } from procedure collections
export const { collections, router } = createRouter(
  healthProcedures,
  userProcedures
);

export type AppRouter = typeof router;
export const routes = extractRoutes(collections);

REST Adapter Options

When using the REST adapter directly:

import { rest } from '@veloxts/router';

app.routes(rest([healthProcedures, userProcedures], {
  prefix: '/api',        // API prefix (default: '/api')
  shortcuts: false,      // Generate flat shortcut routes for nested resources
  nestingWarnings: true, // Warn when nesting exceeds 3 levels
}));

OpenAPI / Swagger UI

OpenAPI documentation is configured separately via the Swagger UI plugin:

import { swaggerPlugin } from '@veloxts/router';

app.register(swaggerPlugin, {
  routePrefix: '/docs',
  collections: [healthProcedures, userProcedures],
  openapi: {
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API documentation',
    },
    servers: [
      { url: 'http://localhost:3030', description: 'Development' },
    ],
    prefix: '/api',
  },
  uiConfig: {
    deepLinking: true,
    tryItOutEnabled: true,
  },
});
// Available at: /docs (UI) and /docs/openapi.json (spec)

Auth Configuration

JWT Options

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

const jwt = jwtManager({
  secret: process.env.JWT_SECRET!,
  refreshSecret: process.env.JWT_REFRESH_SECRET!,
  accessTokenExpiry: '15m',
  refreshTokenExpiry: '7d',

  // Optional: custom claims
  audience: 'my-app',
  issuer: 'my-api',
});

Session Options

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

const session = sessionMiddleware({
  secret: process.env.SESSION_SECRET!,

  store: inMemorySessionStore(), // or redisSessionStore()

  cookie: {
    name: 'session',
    secure: true,
    httpOnly: true,
    sameSite: 'lax',
    path: '/',
    maxAge: 86400,
  },

  expiration: {
    ttl: 86400,
    sliding: true,
    absoluteTimeout: 604800,
  },

  userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
});

Prisma Configuration

prisma.config.ts

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

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

Driver Adapters

// SQLite
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL });

// PostgreSQL
import { PrismaPg } from '@prisma/adapter-pg';
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });

// MySQL
import { PrismaMysql2 } from '@prisma/adapter-mysql';
const adapter = new PrismaMysql2({ url: process.env.DATABASE_URL });

CLI Configuration

velox.config.ts

import { defineConfig } from '@veloxts/cli';

export default defineConfig({
  // Entry point
  entry: './src/index.ts',

  // Output directory
  outDir: './dist',

  // Dev server options
  dev: {
    port: 3030,
    hmr: true,
  },
});

package.json HMR Boundaries

{
  "hotHook": {
    "boundaries": [
      "src/procedures/**/*.ts",
      "src/schemas/**/*.ts",
      "src/handlers/**/*.ts"
    ]
  }
}

Ecosystem Configuration

Cache

import { cachePlugin } from '@veloxts/cache';

app.register(cachePlugin({
  driver: 'redis',
  config: {
    url: process.env.REDIS_URL,
    prefix: 'app:',
    ttl: 3600,
  },
}));

Queue

import { queuePlugin } from '@veloxts/queue';

app.register(queuePlugin({
  driver: 'bullmq',
  config: {
    connection: { url: process.env.REDIS_URL },
    defaultJobOptions: {
      attempts: 3,
      backoff: { type: 'exponential', delay: 1000 },
    },
  },
}));

Mail

import { mailPlugin } from '@veloxts/mail';

app.register(mailPlugin({
  driver: 'resend',
  config: { apiKey: process.env.RESEND_API_KEY },
  defaults: {
    from: 'noreply@example.com',
    replyTo: 'support@example.com',
  },
}));

Storage

import { storagePlugin } from '@veloxts/storage';

app.register(storagePlugin({
  driver: 's3',
  config: {
    bucket: process.env.S3_BUCKET,
    region: process.env.AWS_REGION,
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    },
  },
}));

Related Content

• Environment Configuration - Environment-aware presets
• Environment Variables - Required variables
• Troubleshooting - Common issues