Quickstart

Build your first CRUD API with NestJS CRUD in minutes

Get started with NestJS CRUD by building a complete CRUD API for managing users. This guide will walk you through creating an entity, service, controller, and testing your API.

Prerequisites

Make sure you have completed the installation steps and have a NestJS project set up with TypeORM and NestJS CRUD installed.

Create your first CRUD API

1. Create an entity

   Create a TypeORM entity to define your data model. Add validation decorators from class-validator:

   User.entity.ts

   import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
   import { IsString, IsEmail, IsOptional, MaxLength } from 'class-validator';
   
   @Entity('users')
   export class User {
     @PrimaryGeneratedColumn()
     id: number;
   
     @IsString()
     @MaxLength(100)
     @Column({ type: 'varchar', length: 100 })
     name: string;
   
     @IsEmail()
     @Column({ type: 'varchar', unique: true })
     email: string;
   
     @IsOptional()
     @IsString()
     @Column({ type: 'text', nullable: true })
     bio?: string;
   }
   
2. Create a service

   Create a service that extends TypeOrmCrudService to handle database operations:

   users.service.ts

   import { Injectable } from '@nestjs/common';
   import { InjectRepository } from '@nestjs/typeorm';
   import { TypeOrmCrudService } from '@nestjsx/crud-typeorm';
   import { Repository } from 'typeorm';
   import { User } from './user.entity';
   
   @Injectable()
   export class UsersService extends TypeOrmCrudService<User> {
     constructor(
       @InjectRepository(User)
       repository: Repository<User>,
     ) {
       super(repository);
     }
   }
   

   That’s it! The TypeOrmCrudService provides all CRUD methods out of the box.

3. Create a controller

   Create a controller with the @Crud() decorator to automatically generate REST endpoints:

   users.controller.ts

   import { Controller } from '@nestjs/common';
   import { Crud } from '@nestjsx/crud';
   import { User } from './user.entity';
   import { UsersService } from './users.service';
   
   @Crud({
     model: {
       type: User,
     },
     query: {
       alwaysPaginate: true,
     },
   })
   @Controller('users')
   export class UsersController {
     constructor(public service: UsersService) {}
   }
   

   The @Crud() decorator automatically creates these endpoints:

   • GET /users - Get all users
   • GET /users/:id - Get one user
   • POST /users - Create user
   • POST /users/bulk - Create multiple users
   • PATCH /users/:id - Update user
   • PUT /users/:id - Replace user
   • DELETE /users/:id - Delete user
4. Register the module

   Register your entities and services in a NestJS module:

   users.module.ts

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   import { User } from './user.entity';
   import { UsersService } from './users.service';
   import { UsersController } from './users.controller';
   
   @Module({
     imports: [TypeOrmModule.forFeature([User])],
     controllers: [UsersController],
     providers: [UsersService],
   })
   export class UsersModule {}
   

Test your API

Start your NestJS application and test the auto-generated endpoints:

Create a user

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[e-mail]",
    "bio": "Software developer"
  }'

curl http://localhost:3000/users

curl http://localhost:3000/users/1

curl -X PATCH http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"bio": "Senior software developer"}'

curl -X DELETE http://localhost:3000/users/1

Advanced querying

NestJS CRUD provides powerful query capabilities out of the box. Try these advanced queries:

Filter by name

curl "http://localhost:3000/users?filter=name||eq||John%20Doe"

curl "http://localhost:3000/users?filter=name||cont||John"

curl "http://localhost:3000/users?page=1&limit=10"

curl "http://localhost:3000/users?sort=name,ASC"

curl "http://localhost:3000/users?fields=id,name,email"

curl "http://localhost:3000/users?filter=name||cont||John&filter=email||cont||example"

Filter operators

NestJS CRUD supports a wide range of filter operators:

Operator	Description	Example
$eq	Equals	`filter=name		eq		John`
$ne	Not equals	`filter=name		ne		John`
$gt	Greater than	`filter=age		gt		18`
$lt	Less than	`filter=age		lt		65`
$gte	Greater than or equal	`filter=age		gte		21`
$lte	Less than or equal	`filter=age		lte		100`
$starts	Starts with	`filter=name		starts		Jo`
$ends	Ends with	`filter=email		ends		.com`
$cont	Contains	`filter=name		cont		oh`
$excl	Excludes	`filter=name		excl		test`
$in	In array	`filter=id		in		1,2,3`
$notin	Not in array	`filter=id		notin		4,5`
$isnull	Is null	`filter=bio		isnull`
$notnull	Is not null	`filter=bio		notnull`
$between	Between values	`filter=age		between		18,65`

Add L suffix to any operator for case-insensitive comparisons (e.g., $contL, $startsL, $eqL)

Configure query options

Customize the query behavior in your controller:

users.controller.ts

@Crud({
  model: {
    type: User,
  },
  query: {
    alwaysPaginate: true,
    limit: 20,
    maxLimit: 100,
    sort: [{ field: 'id', order: 'DESC' }],
    join: {
      posts: {
        eager: true,
        alias: 'userPosts',
      },
    },
  },
})
@Controller('users')
export class UsersController {
  constructor(public service: UsersService) {}
}

Override endpoints

You can override any auto-generated endpoint to add custom logic:

users.controller.ts

import { Override, ParsedRequest, CrudRequest } from '@nestjsx/crud';

@Crud({
  model: { type: User },
})
@Controller('users')
export class UsersController {
  constructor(public service: UsersService) {}

  @Override()
  async getOne(@ParsedRequest() req: CrudRequest) {
    console.log('Custom logic before fetching user');
    return this.service.getOne(req);
  }

  @Override('createOneBase')
  async createOne(
    @ParsedRequest() req: CrudRequest,
    @ParsedBody() dto: User,
  ) {
    // Add custom validation or business logic
    console.log('Creating user:', dto);
    return this.service.createOne(req, dto);
  }
}

Next steps

Query parameters

Learn about all available query parameters and filtering options

Controllers

Understand CRUD controllers and configuration options

Services

Dive deeper into CRUD services and custom implementations

Advanced features

Explore authentication, serialization, and Swagger integration