Application

Every Velox TS app starts with veloxApp(). It creates a configured Fastify instance with sensible defaults, registers your plugins and routes, and manages the server lifecycle. This is the entry point for everything your application does.

Creating an App

import { veloxApp, rest } from '@veloxts/velox';
import { userProcedures } from './procedures/users.js';

const app = await veloxApp({ port: 3030 });

// Register routes
app.routes(rest([userProcedures], { prefix: '/api' }));

await app.start();

Configuration Options

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

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

  // Logging (Pino)
  logger: true,  // or detailed pino config object
});

CORS Configuration

const app = await veloxApp({
  cors: {
    origin: ['http://localhost:5173', 'https://myapp.com'],
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
    credentials: true,
    allowedHeaders: ['Content-Type', 'Authorization'],
  },
});

Logging

const app = await veloxApp({
  logger: {
    level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
    transport: {
      target: 'pino-pretty',
      options: { colorize: true },
    },
  },
});

Application Lifecycle

await veloxApp()     Create instance
    │
    ▼
app.register()       Register plugins
app.routes()         Register routes
    │
    ▼
app.start()          Begin listening
    │
    ▼
app.stop()           Graceful shutdown

Lifecycle Events

const app = await veloxApp({ port: 3030 });

// Called when app is ready but not yet listening
app.server.addHook('onReady', async () => {
  console.log('App ready');
});

// Called when app starts listening
app.server.addHook('onListen', async () => {
  console.log('Server listening');
});

// Called during shutdown
app.server.addHook('onClose', async () => {
  console.log('Server closing');
});

Graceful Shutdown

Velox TS handles shutdown signals automatically. For database connections, add explicit cleanup:

import { veloxApp, rest } from '@veloxts/velox';
import { db } from './config/database.js';
import { userProcedures } from './procedures/users.js';

const app = await veloxApp({ port: 3030 });

app.routes(rest([userProcedures], { prefix: '/api' }));

await app.start();

// Graceful shutdown - prevent connection leaks
const shutdown = async () => {
  await db.$disconnect();  // Disconnect Prisma
  await app.stop();        // Stop server
  process.exit(0);
};

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

Development Server (HMR)

The Velox TS CLI provides a development server with Hot Module Replacement:

velox dev              # Start with HMR (default)
velox dev --no-hmr     # Legacy tsx watch mode
velox dev --verbose    # Detailed HMR diagnostics
velox dev --port 4000  # Custom port

HMR Features

Sub-second restart times
Precise timing metrics (startup, reload, uptime)
Smart error classification with suggestions
Visual indicators in console output

HMR Boundaries

Configure which files trigger reloads in package.json:

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

Ready Signal for Accurate Timing

For precise HMR timing metrics, add the ready signal after starting:

await app.start();

// Signal to CLI that server is ready
if (process.send) {
  process.send({ type: 'velox:ready' });
}

The CLI listens for this message to measure actual server boot time versus process startup time.

Accessing Fastify

The underlying Fastify instance is available via app.server when needed:

const app = await veloxApp({ port: 3030 });

// Access Fastify directly
app.server.get('/custom', async (request, reply) => {
  return { custom: true };
});

// Register Fastify plugins
await app.server.register(import('@fastify/helmet'));

Health Check Endpoint

All Velox TS apps include a health check at /api/health:

curl http://localhost:3030/api/health
# {"status":"ok","timestamp":"2024-01-15T10:30:00Z"}

Environment-Based Configuration

const app = await veloxApp({
  port: parseInt(process.env.PORT ?? '3030'),
  host: process.env.HOST ?? '0.0.0.0',
  logger: process.env.NODE_ENV === 'production'
    ? { level: 'warn' }
    : { level: 'debug', transport: { target: 'pino-pretty' } },
  cors: {
    origin: process.env.CORS_ORIGINS?.split(',') ?? ['http://localhost:3000'],
  },
});

Context - Request context
Plugins - Extend functionality
Configuration - Environment setup