Skip to main content

​
Overview

The global configuration allows you to set default options that apply to all CRUD controllers in your application. This helps maintain consistency and reduces repetition across your codebase.
Global configuration must be loaded before importing your AppModule. This ensures that all controllers inherit the correct settings.

​
Basic Setup

Load global configuration in your main.ts file:
main.ts
import { NestFactory } from '@nestjs/core';
import { CrudConfigService } from '@nestjsx/crud';

// Load config BEFORE importing AppModule
CrudConfigService.load({
  auth: {
    property: 'user',
  },
  query: {
    limit: 25,
    maxLimit: 100,
    cache: 2000,
    alwaysPaginate: false,
  },
  routes: {
    exclude: ['createManyBase'],
  },
});

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

​
Configuration Options

​
Query Options

Control query behavior across all endpoints: 
CrudConfigService.load({
  query: {
    limit: 25,              // Default number of items per page
    maxLimit: 100,          // Maximum allowed limit
    cache: 2000,            // Cache duration in milliseconds
    alwaysPaginate: false,  // Always return paginated responses
    softDelete: false,      // Enable soft delete by default
  },
});

​
Query Parameters

ParameterTypeDescription
limitnumberDefault number of items returned in getMany requests
maxLimitnumberMaximum limit users can request
cachenumber | falseCache duration in milliseconds, or false to disable
alwaysPaginatebooleanIf true, always return paginated format
softDeletebooleanEnable soft delete functionality globally

​
Routes Options

Configure which routes are available by default: 
CrudConfigService.load({
  routes: {
    // Exclude specific routes globally
    exclude: ['createManyBase'],
    
    // Configure specific route options
    deleteOneBase: {
      returnDeleted: false,
    },
    createOneBase: {
      returnShallow: false,
    },
    updateOneBase: {
      allowParamsOverride: false,
      returnShallow: false,
    },
  },
});
You can override global route settings in individual controllers using the @Crud() decorator.

​
Auth Options

Set global authentication property: 
CrudConfigService.load({
  auth: {
    property: 'user',
  },
});
This specifies the request property where the authenticated user object is stored (e.g., req.user).

​
Query Parser Options

Customize query string parsing: 
import { RequestQueryBuilder } from '@nestjsx/crud-request';

CrudConfigService.load({
  queryParser: {
    delim: '||',
    delimStr: ',',
    paramNamesMap: {
      fields: ['fields', 'select'],
      search: 's',
      filter: ['filter', 'where'],
      or: 'or',
      join: ['join', 'relations'],
      sort: 'sort',
      limit: 'limit',
      offset: 'offset',
      page: 'page',
      cache: 'cache',
    },
  },
});

​
Serialization Options

Disable serialization globally for specific operations: 
CrudConfigService.load({
  serialize: {
    get: false,       // Disable for getOne
    getMany: false,   // Disable for getMany
    create: false,    // Disable for create
    update: false,    // Disable for update
    replace: false,   // Disable for replace
    delete: false,    // Disable for delete
  },
});
Setting serialization to false globally will disable DTOs for all controllers unless explicitly overridden.

​
Params Options

Define global parameter configurations: 
CrudConfigService.load({
  params: {
    id: {
      field: 'id',
      type: 'number',
      primary: true,
    },
  },
});

​
Complete Example

Here’s a comprehensive global configuration:
main.ts
import { NestFactory } from '@nestjs/core';
import { CrudConfigService } from '@nestjsx/crud';

CrudConfigService.load({
  // Authentication
  auth: {
    property: 'user',
  },
  
  // Query defaults
  query: {
    limit: 20,
    maxLimit: 100,
    cache: 2000,
    alwaysPaginate: false,
    softDelete: true,
  },
  
  // Route configuration
  routes: {
    exclude: ['createManyBase'],
    deleteOneBase: {
      returnDeleted: false,
    },
    updateOneBase: {
      allowParamsOverride: false,
      returnShallow: false,
    },
  },
  
  // Query parser
  queryParser: {
    delim: '||',
    delimStr: ',',
  },
});

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

​
Override in Controllers

Global settings can be overridden in individual controllers:
users.controller.ts
@Crud({
  model: { type: User },
  query: {
    limit: 50,           // Override global limit
    alwaysPaginate: true, // Override global setting
  },
  routes: {
    only: ['getManyBase', 'getOneBase'], // Override global routes
  },
})
@Controller('users')
export class UsersController {
  constructor(public service: UsersService) {}
}

​
Best Practices

1

Load Early

Always load global configuration before importing AppModule to ensure all controllers use the settings.
2

Set Sensible Defaults

Configure reasonable default values that work for most of your application.
3

Document Overrides

Clearly document when and why you override global settings in specific controllers.
4

Consider Security

Set appropriate maxLimit values to prevent abuse of your API.

Build docs developers (and LLMs) love

Get started for freeTalk to us