Getting Started

This guide walks you through installing tsgonest, configuring it for a NestJS project, and running your first build.

Prerequisites

Node.js 18 or later
An existing NestJS project (or any TypeScript project)
A package manager: npm, pnpm, yarn, or bun

Installation

Install tsgonest and its companion packages:

npm install tsgonest

The tsgonest package includes the CLI binary and automatically installs @tsgonest/runtime and @tsgonest/types as dependencies.

tsgonest ships pre-built native binaries for macOS (ARM64, x64), Linux (ARM64, x64), and Windows (x64). The correct binary is selected automatically during npm install.

Project setup

1. Create a configuration file

Create tsgonest.config.ts in your project root:

tsgonest.config.ts

import { defineConfig } from '@tsgonest/runtime';

export default defineConfig({
  controllers: {
    include: ['src/**/*.controller.ts'],
  },
  transforms: {
    validation: true,
    serialization: true,
  },
  openapi: {
    output: 'dist/openapi.json',
  },
});

The defineConfig() helper provides full autocomplete and type checking. tsgonest auto-detects this file in your working directory.

2. Define your DTOs

Create a DTO file with validation constraints. You can use either JSDoc tags or branded types:

src/user/user.dto.ts

import { Min, Max, Email, Trim } from '@tsgonest/types';

export interface CreateUserDto {
  name: string & Trim & Min<1> & Max<255>;
  email: string & Email;
  age: number & Min<0> & Max<150>;
}

export interface UserResponse {
  id: string;
  name: string;
  email: string;
  age: number;
  createdAt: string;
}

Or with JSDoc tags (no @tsgonest/types dependency):

src/user/user.dto.ts

export interface CreateUserDto {
  /**
   * @transform trim
   * @minLength 1
   * @maxLength 255
   */
  name: string;

  /** @format email */
  email: string;

  /**
   * @minimum 0
   * @maximum 150
   */
  age: number;
}

export interface UserResponse {
  id: string;
  name: string;
  email: string;
  age: number;
  createdAt: string;
}

3. Create a controller

src/user/user.controller.ts

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { CreateUserDto, UserResponse } from './user.dto';

@Controller('users')
export class UserController {
  @Post()
  create(@Body() dto: CreateUserDto): UserResponse {
    // tsgonest generates validation for CreateUserDto
    // and serialization for UserResponse automatically
    return {
      id: '1',
      name: dto.name,
      email: dto.email,
      age: dto.age,
      createdAt: new Date().toISOString(),
    };
  }

  @Get(':id')
  findOne(@Param('id') id: string): UserResponse {
    return {
      id,
      name: 'John',
      email: 'john@example.com',
      age: 30,
      createdAt: new Date().toISOString(),
    };
  }
}

4. Build

npx tsgonest build

This compiles your TypeScript, generates companion files, injects validation and serialization into your controllers, and produces the OpenAPI document — all in one command.

You should see output like:

tsgonest v0.3.0 build
  tsconfig: tsconfig.json
  config:   tsgonest.config.ts

  emit:        142ms
  companions:  38ms  (4 files)
  openapi:     12ms

  total: 192ms

That's it — zero runtime setup needed. tsgonest injects assertTypeName() calls for @Body(), @Query(), @Param(), and @Headers() parameters, and wraps return statements with transformTypeName() at compile time. Query and path parameters get automatic string-to-number/boolean coercion. No pipes, interceptors, or manifest needed.

Development mode

Use tsgonest dev for watch-mode development with automatic rebuild and restart:

npx tsgonest dev

This watches your source files, rebuilds on changes, and restarts your Node.js process automatically. It replaces nest start --watch.

# With a custom entry point
npx tsgonest dev --entry src/main.ts

# With environment files
npx tsgonest dev --env-file .env --env-file .env.local

# With Node.js inspector for debugging
npx tsgonest dev --debug

Type rs and press Enter to manually restart during development (if manualRestart is enabled in your config).

Update package.json scripts

Replace your existing build and dev scripts:

package.json

{
  "scripts": {
    "build": "tsgonest build",
    "start:dev": "tsgonest dev",
    "start:prod": "node dist/main.js"
  }
}

Verify the output

After building, check your dist/ directory:

ls dist/

You should see:

Your compiled JavaScript files
*.tsgonest.js and *.tsgonest.d.ts companion files alongside each DTO
openapi.json with your complete API documentation
Controller JS files with injected validation and serialization calls

Getting Started

Prerequisites

Installation

Project setup

1. Create a configuration file

2. Define your DTOs

3. Create a controller

4. Build

Development mode

Update package.json scripts

Verify the output

What's next

CLI Reference

Configuration

Validation

Serialization & Runtime

On this page