Body Parser

The allowedMethods array defines which HTTP methods should have their request bodies parsed. By default, only POST, PUT, PATCH, and DELETE requests are processed. GET requests are excluded because they typically don't include request bodies.

The convertEmptyStringsToNull option converts all empty strings in the request body to null values. This option solves a common problem with HTML forms.

When an HTML form input field has no value, browsers send an empty string in the request body rather than omitting the field entirely. This behavior creates challenges for database normalization, especially with nullable columns.

Consider a user registration form with an optional "country" field. Your database has a nullable country column, and you want to store null when the user doesn't select a country. However, the HTML form sends an empty string, which means you would insert an empty string into the database instead of leaving the column as null.

Enabling convertEmptyStringsToNull handles this inconsistency automatically. The body parser converts all empty strings to null before your validation or database logic runs.

json: {
  convertEmptyStringsToNull: true,
}

The trimWhitespaces option removes leading and trailing whitespace from all string values in the request body. This helps eliminate accidental whitespace that users might include when submitting forms.

Instead of manually trimming values in your controllers or validators, you can enable this option and let the body parser handle whitespace removal globally.

form: {
  trimWhitespaces: true,
}

The encoding option specifies the character encoding to use when converting the request body Buffer to a string. The default is utf-8, which handles most use cases. You can use any encoding supported by the iconv-lite package.

json: {
  encoding: 'utf-8',
}

The limit option sets the maximum size of request body data the parser will accept. Requests that exceed this limit will receive a 413 Payload Too Large error response.

json: {
  limit: '1mb',
}

The strict option controls whether the parser accepts only objects and arrays as top-level JSON values. When enabled, the parser rejects primitive values like strings, numbers, or booleans at the root level.

json: {
  strict: true,
}

The types array defines which content types the JSON parser should handle. You can add custom content types if your application receives JSON data with non-standard content type headers.

json: {
  types: [
    'application/json',
    'application/json-patch+json',
    'application/vnd.api+json',
    'application/csp-report',
    'application/custom+json',
  ]
}

The encoding option specifies the character encoding to use when converting the request body Buffer to a string. The default is utf-8, which handles most use cases. You can use any encoding supported by the iconv-lite package.

form: {
  encoding: 'utf-8',
}

The limit option sets the maximum size of request body data the parser will accept. Requests that exceed this limit will receive a 413 Payload Too Large error response.

form: {
  limit: '1mb',
}

The queryString option allows you to configure how the URL-encoded string is parsed into an object. These options are passed directly to the qs package, which handles the parsing.

form: {
  queryString: {
    depth: 5,
    parameterLimit: 1000,
  },
}

See also: qs documentation for all available options.

The types array defines which content types the form parser should handle. By default, it processes application/x-www-form-urlencoded requests.

form: {
  types: ['application/x-www-form-urlencoded'],
}

The autoProcess option controls whether uploaded files are automatically moved to your operating system's temporary directory. When enabled, the parser streams files to disk as the request is processed.

After automatic processing, you can access uploaded files in your controllers using request.file(), validate them, and move them to a permanent location or cloud storage service.

multipart: {
  autoProcess: true,
}

You can specify an array of route patterns to enable automatic processing for specific routes only. The values must be route patterns, not URLs.

multipart: {
  autoProcess: [
    '/uploads',
    '/posts/:id/images',
  ],
}

The processManually array lets you disable automatic file processing for selected routes while keeping it enabled globally. This is useful when you have a few routes that need custom file handling but want the convenience of automatic processing everywhere else.

The values must be route patterns, not URLs.

multipart: {
  autoProcess: true,
  processManually: [
    '/file-manager',
    '/projects/:id/assets',
  ],
}

The encoding option specifies the character encoding to use when converting text fields in the multipart request to strings. The default is utf-8, which handles most use cases. You can use any encoding supported by the iconv-lite package.

multipart: {
  encoding: 'utf-8',
}

The limit option sets the maximum total size of all uploaded files in a single request. Requests that exceed this limit will receive a 413 Payload Too Large error response.

multipart: {
  limit: '20mb',
}

The fieldsLimit option sets the maximum total size of all form fields (not files) in the multipart request. This prevents abuse through extremely large text field submissions. Requests that exceed this limit will receive a 413 Payload Too Large error response.

multipart: {
  fieldsLimit: '2mb',
}

The tmpFileName option accepts a function that generates custom names for temporary files. By default, the parser generates random file names.

multipart: {
  tmpFileName: () => {
    return `upload_${Date.now()}_${Math.random().toString(36)}`
  },
}

The types array defines which content types the multipart parser should handle. By default, it processes multipart/form-data requests.

multipart: {
  types: ['multipart/form-data'],
}