@Crud() decorator

Learn how to use the @Crud() decorator to generate RESTful API routes

The @Crud() decorator is the core feature of NestJS CRUD. It automatically generates RESTful API routes for your controller based on the configuration you provide.

Basic usage

Apply the @Crud() decorator to your controller class to generate CRUD routes:

import { Controller } from '@nestjs/common';
import { Crud } from '@nestjsx/crud';
import { User } from './user.entity';
import { UsersService } from './users.service';

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

This minimal configuration generates the following routes:

• GET /users - Get many users
• GET /users/:id - Get one user
• POST /users - Create one user
• POST /users/bulk - Create many users
• PATCH /users/:id - Update one user
• PUT /users/:id - Replace one user
• DELETE /users/:id - Delete one user

Configuration options

The @Crud() decorator accepts a CrudOptions object with the following properties:

model · ModelOptions · required

The entity model for this controller. Must include a type property with your entity class.

model: {
  type: User,
}

dto · DtoOptions

Custom DTOs for create, update, and replace operations.

dto: {
  create: CreateUserDto,
  update: UpdateUserDto,
  replace: ReplaceUserDto,
}

serialize · SerializeOptions

Response serialization options for each route. Use DTOs to transform response data.

serialize: {
  get: GetUserResponseDto,
  getMany: GetUserResponseDto,
}

query · QueryOptions

Query configuration including filtering, sorting, pagination, and joins.

See Query options for details.

routes · RoutesOptions

Route-specific configuration to customize or exclude individual routes.

See Route options for details.

params · ParamsOptions

URL parameter configuration for path parameters.

See CRUD options for details.

validation · ValidationPipeOptions | false

Validation pipe options or false to disable validation.

See Validation for details.

Examples

With query configuration

@Crud({
  model: {
    type: Company,
  },
  query: {
    alwaysPaginate: false,
    softDelete: true,
    allow: ['name'],
    join: {
      users: {
        alias: 'companyUsers',
        exclude: ['email'],
        eager: true,
      },
      projects: {
        eager: true,
        select: false,
      },
    },
  },
})
@Controller('companies')
export class CompaniesController {
  constructor(public service: CompaniesService) {}
}

With nested routes and params

@Crud({
  model: {
    type: Project,
  },
  params: {
    companyId: {
      field: 'companyId',
      type: 'number',
    },
    id: {
      field: 'id',
      type: 'number',
      primary: true,
    },
  },
  query: {
    join: {
      users: {},
    },
  },
})
@Controller('/companies/:companyId/projects')
export class ProjectsController {
  constructor(public service: ProjectsService) {}
}

With custom DTOs and serialization

@Crud({
  model: { type: Note },
  dto: {
    create: CreateNoteDto,
  },
  serialize: {
    get: GetNoteResponseDto,
  },
  query: {
    alwaysPaginate: true,
  },
})
@Controller('/notes')
export class NotesController {
  constructor(public service: NotesService) {}
}

With UUID primary key

@Crud({
  model: { type: Device },
  params: {
    deviceKey: {
      field: 'deviceKey',
      type: 'uuid',
      primary: true,
    },
  },
  routes: {
    deleteOneBase: {
      returnDeleted: true,
    },
  },
})
@Controller('/devices')
export class DevicesController {
  constructor(public service: DevicesService) {}
}

Controller implementation

Your controller’s service must be exposed as a public property named service. The CRUD decorator uses this to access your service methods.

Minimal implementation

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

With CrudController interface

For better type safety, implement the CrudController interface:

import { CrudController } from '@nestjsx/crud';

@Crud({
  model: { type: User },
})
@Controller('users')
export class UsersController implements CrudController<User> {
  constructor(public service: UsersService) {}
  
  get base(): CrudController<User> {
    return this;
  }
}

Generated route names

The decorator generates these base route methods that you can override:

• getManyBase - Get multiple entities
• getOneBase - Get a single entity
• createOneBase - Create a single entity
• createManyBase - Create multiple entities (bulk)
• updateOneBase - Update a single entity (partial)
• replaceOneBase - Replace a single entity (full)
• deleteOneBase - Delete a single entity
• recoverOneBase - Recover a soft-deleted entity

See Overriding routes to learn how to customize these methods.

Related topics

CRUD options

Detailed reference for all configuration options

Route options

Configure individual routes

Overriding routes

Customize generated route handlers

Validation

Configure request validation