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 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 { VeloceTS, Controller, Get, Post, Body, Query, Param } 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(@Query() query: any) {
    const { limit = 10, offset = 0 } = query;
    return {
      users: [
        { id: 1, name: 'John Doe', email: 'john@example.com' },
        { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
      ],
      pagination: { limit, offset, total: 2 }
    };
  }

  @Get('/:id')
  async getUser(@Param('id') id: string) {
    return { id: parseInt(id), name: 'John Doe', email: 'john@example.com' };
  }

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

// Create and start the app
const app = new VeloceTS({
  title: 'My API',
  version: '1.0.0'
});
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:

# Create a new project
veloce-ts new my-api --template rest

# Start development server
veloce-ts dev

# Build for production
veloce-ts build

# Generate OpenAPI spec
veloce-ts generate openapi

Next Steps

• Learn about Decorators
• Explore Dependency Injection
• Check out Plugins
• Read the API Reference