# NestJS CRUD API

A NestJS 12 CRUD API starter in TypeScript for Node.js 22 that stores one resource, items, in PostgreSQL through node-postgres and a connection pool. It is for developers who want Nest modules, class-validator DTOs, Swagger UI at /docs, JSON errors, limit and offset paging and a database /health check, ready to rename.

- Framework: NestJS (JavaScript)
- Category: Starters / CRUD APIs
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/crud-apis/nestjs-postgresql-crud-api
- Updated: 2026-11-21

## Features

- ItemsController with GET, POST, PUT and DELETE on /items, and GET /items?limit=20&offset=0 paging capped at 100
- One module each for items, health and database; a global DatabaseService holds a pg pool of up to 5 connections
- class-validator DTOs and a global ValidationPipe: name is trimmed to 1 to 200 characters and unknown fields are stripped
- Swagger UI at /docs and the OpenAPI schema at /docs-json, generated by @nestjs/swagger from the DTOs
- One JsonErrorFilter turns every error into { "error": "..." }: 400 for bad input, 404 for unknown items and routes
- ItemIdPipe answers 404 for ids that are not whole numbers or exceed the 32-bit SERIAL range
- GET /health answers 200, or 503 when SELECT 1 fails; the items table is created in onModuleInit, with no migrations
- node:test tests on Nest's testing module: HTTP tests use a fake database, a CRUD test runs when DATABASE_URL is set

## What you need

- A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
- To run it locally: Node.js 22 or newer, npm, and Docker for a local PostgreSQL
- No API keys: it starts with nothing to configure
- DATABASE_URL: Light Cloud sets it on deploy; for local runs you export it, as the app does not read .env

## About

configureApp in src/app.setup.ts applies the validation pipe, the error filter, Swagger and shutdown hooks, and the tests call the same function, so they run the app the way it is deployed. ItemsService is the only file that writes SQL, which keeps a later move to TypeORM, Prisma or Drizzle inside one service. The build is plain tsc with TypeScript 6 into dist/, and npm run build is the type check, since no linter is configured. Renaming items starts with the src/items/ folder and the CREATE TABLE in src/database/database.service.ts. On Light Cloud the deploy runs npm run build, then npm start (node dist/main.js) with DATABASE_URL set, and every push to your copy redeploys.

## Questions

### How do I connect NestJS to PostgreSQL without TypeORM?

This starter does it with node-postgres: a global DatabaseService opens a pg pool from DATABASE_URL, and ItemsService runs parameterised SQL through it. You can swap in TypeORM, Prisma or Drizzle inside ItemsService without touching the controller.

### How do I add Swagger docs to a NestJS API?

They are set up here already: configureApp in src/app.setup.ts calls SwaggerModule.setup('docs', ...), so Swagger UI is at /docs and the schema at /docs-json. New DTOs with @ApiProperty decorators show up after the next build.

### How do I add a new resource in NestJS?

Copy the src/items/ folder (module, controller, service and DTOs), add its CREATE TABLE to onModuleInit in src/database/database.service.ts and import the new module in src/app.module.ts.

### How do I deploy a NestJS app with a PostgreSQL database?

Press Deploy on this template: Light Cloud copies the repo into your GitHub account, creates a PostgreSQL database, sets DATABASE_URL and runs npm run build, then npm start. Databases need a paid plan.

### Can I host this NestJS API without Light Cloud?

Yes. It has no Light Cloud code: any host with Node.js 22 and a reachable PostgreSQL runs it with npm install, npm run build and npm start, given DATABASE_URL and PORT.
