Getting Started

Getting Started

Welcome to Veloce-TS! This guide will help you get up and running quickly with the latest features and improvements.

:::tip What’s New in v1.2.0

• CLI scaffolding — veloce generate controller/service/module/resolver/dto/middleware/plugin <name> generates typed boilerplate instantly
• Graceful shutdown — app.onShutdown(handler) + automatic SIGTERM/SIGINT handling; configurable timeout
• Exception filters — @Catch(ErrorClass) + app.useFilter() for centralized, typed error responses
• Interceptors — @UseInterceptor() + app.useInterceptor() for AOP logging, caching, and transforms
• Streaming — @SSE() and @Stream(contentType) on AsyncGenerator handlers for SSE and CSV exports
• Event bus — EventBus and globalEvents singleton for in-process pub/sub without Redis
• Extra decorators — @Throttle, @ApiVersion, @ResponseHeader, @Redirect, @Deprecated
• Test isolation — isolate() and compileTestApp() for flake-free parallel tests
• OpenAPI 3.1 — jsonSchemaDialect, nullable → type: ['x','null'] :::

:::tip What’s New in v1.0.1

• GraphQL decorator pipeline fixed — @Resolver, @GQLQuery, @GQLMutation, and @Arg work end-to-end. Pass resolver classes via resolvers: [...] on the plugin or app.include().
• PermissionManager.revokePermission() fixed — permissions are now removed correctly when no resourceId is specified.
• 509 tests — 89 new tests covering PermissionPlugin, HealthCheckPlugin, Logger, OAuthPlugin, and GraphQL. :::

:::tip What’s New in v0.4.0

• New OpenAPI shorthand decorators — @Summary, @Description, @Tag, @Tags, @Deprecated for concise route documentation
• Response control decorators — @HttpCode(statusCode) and @ResponseSchema(schema) to control and document responses
• Per-route middleware decorators — @Timeout(ms) and @RateLimit(options) applied declaratively
• Fluent TestClient — new TestResponse with chainable assertions (expectOk(), expectJson(), expectField())
• Drizzle ORM DI integration — registerDrizzle() and @InjectDB() for clean database injection
• 6 new HTTP exception classes — ConflictException, GoneException, PayloadTooLargeException, UnprocessableEntityException, TooManyRequestsException, ServiceUnavailableException
• Auto-tagging and Bearer security in OpenAPI generator
• Improved validation error shape — structured field, received, expected, minimum/maximum in 422 responses :::

Installation

Install Veloce using your preferred package manager:

# Using Bun (recommended)
bun add veloce-ts zod

# Using npm
npm install veloce-ts zod

# Using pnpm
pnpm add veloce-ts zod

Quick Start

Create your first API in minutes:

import { Veloce, Controller, Get, Post, Body } from 'veloce-ts';
import { z } from 'zod';

// Define schemas
const UserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

// Create a controller
@Controller('/users')
class UserController {
  @Get('/')
  async getUsers() {
    return [
      { id: 1, name: 'John Doe', email: 'john@example.com' },
      { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
    ];
  }

  @Post('/')
  async createUser(@Body(UserSchema) user: z.infer<typeof UserSchema>) {
    return { id: 3, ...user };
  }
}

// Create and start the app
const app = new Veloce();
app.include(UserController);
app.listen(3000);

console.log('Server running on http://localhost:3000');

TypeScript Configuration

Add these settings to your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Project Structure

A typical Veloce-TS project structure:

my-api/
├── src/
│   ├── controllers/
│   │   └── user.controller.ts
│   ├── services/
│   │   └── user.service.ts
│   ├── schemas/
│   │   └── user.schema.ts
│   └── index.ts
├── package.json
└── tsconfig.json

Using the CLI

Veloce-TS includes a powerful CLI tool for project creation and code generation:

# Create a new project
veloce new my-api

# Generate a full module (controller + service + DTO + barrel)
veloce generate module users

# Generate individual pieces
veloce generate controller products
veloce generate service products
veloce generate dto create-product
veloce generate resolver user
veloce generate middleware auth
veloce generate plugin analytics

See the CLI guide for all options.

Next Steps

• CLI guide — code generation reference
• Exception Filters — centralized error handling
• Interceptors — AOP logging and caching
• Streaming — SSE and streaming responses
• Event Bus — in-process pub/sub
• Decorators — full decorator reference
• Dependency Injection
• Plugins
• API Reference