Celebrate

Common errors

• TypeError: celebrate is not a function

  cause Incorrect import statement or mixing CommonJS `require` with ES Modules `import` syntax without proper configuration.
  fix For ES Modules and TypeScript: `import { celebrate } from 'celebrate';`. For CommonJS: `const { celebrate } = require('celebrate');`. Ensure `package.json` has `"type": "module"` for ESM.

• ValidationError: "someField" is required

  cause A Joi schema marked a field as `required()` but it was missing from the incoming request payload.
  fix Ensure the client is sending all required fields as defined in your Joi schema. Double-check field names and casing.

• Cannot read properties of undefined (reading 'json')

  cause You are attempting to validate `req.body` with `celebrate`, but a body-parsing middleware like `body-parser` (or Express's built-in `express.json()`) has not been applied before `celebrate`.
  fix Add `app.use(bodyParser.json());` or `app.use(express.json());` before your `celebrate` middleware. Ensure it's active for the routes where `req.body` validation occurs.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... celebrated.js not supported.

  cause You are attempting to `require()` an ES Module in a CommonJS context, often when `celebrate` (or its dependencies) have transitioned to ESM-only.
  fix Transition your project to ES Modules by adding `"type": "module"` to your `package.json` and updating all `require()` statements to `import` statements. Alternatively, investigate if a CommonJS-compatible version or wrapper is available.

Warnings

• breaking `Joi` is now a named export. If you were previously importing `Joi` as a default export or through `require('celebrate').Joi`, you must update your import statement.
  Fix: Change `import Joi from 'celebrate'` to `import { Joi } from 'celebrate';` or `const { Joi } = require('celebrate');` for CommonJS.
• breaking The default validation `Modes` changed from `FULL` to `PARTIAL`. This means validation will now stop on the first error encountered, rather than collecting all errors across all segments.
  Fix: If you require the previous behavior of collecting all validation errors before responding, explicitly set `opts.mode = Modes.FULL` in the `celebrate` middleware options. `import { celebrate, Modes } from 'celebrate'; celebrate(schema, null, { mode: Modes.FULL })`.
• breaking Celebrate now requires Joi v17 or newer. Additionally, `req.params` validation logic and general error handling mechanisms were significantly updated. The `celebrator` API was also deprecated.
  Fix: Ensure `joi` is updated to a compatible version (v17+). Review error handling and `req.params` schema definitions. Migrate away from `celebrator` if used.
• breaking The `Joi` export from `celebrate` was renamed from `Joi` to `@hapi/joi` to reflect the package name change in the Joi ecosystem at the time.
  Fix: If importing Joi directly from `celebrate`, ensure you are using the correct named import: `import { Joi } from '@hapi/celebrate';` or `const { Joi } = require('@hapi/celebrate');`. In later versions, it reverted to `Joi` from `celebrate`.
• breaking Celebrate dropped support for Node.js versions older than 10.x. This impacts deployment environments and local development setups.
  Fix: Upgrade Node.js to version 10 or newer. It is recommended to use an actively maintained Node.js LTS version.
• gotcha Celebrate mutates the request object (`req.body`, `req.query`, etc.) when Joi schemas apply default values, coercions, or transformations. This means the request object passed to subsequent middleware or route handlers might differ from the original incoming request.
  Fix: Be aware that the `req` object can be modified. If you need the original request data, consider cloning it before `celebrate` middleware or using Joi's `stripUnknown` option if you only want to remove unvalidated properties.
• gotcha Celebrate (and Joi) will not validate `req.body` for HTTP GET requests by default, as the HTTP specification states GET requests should not contain a body.
  Fix: Avoid sending bodies with GET requests. Use `req.query` or `req.params` for data in GET requests and define your schemas accordingly.

Install

• npm install celebrate npm
• yarn add celebrate yarn
• pnpm add celebrate pnpm

Imports

• celebrate
  wrong:

  const celebrate = require('celebrate');

  correct:

  import { celebrate } from 'celebrate';

  For ESM modules or TypeScript, use named import. CommonJS applications use `require()`. Ensure `type: module` in `package.json` for ESM.
• Joi
  wrong:

  import Joi from 'joi';

  correct:

  import { Joi } from 'celebrate';

  Celebrate exports its internally used Joi instance. This is recommended to ensure compatibility with Celebrate's version of Joi. Direct import from 'joi' is possible but less compatible.
• errors
  wrong:

  const errors = require('celebrate').errors;

  correct:

  import { errors } from 'celebrate';

  The `errors()` middleware should be placed after your routes to catch validation errors and format them consistently.
• Segments
  wrong:

  const { Segments } = require('celebrate').Segments;

  correct:

  import { Segments } from 'celebrate';

  Used to specify which part of the request object (e.g., `Segments.BODY`, `Segments.QUERY`) the Joi schema applies to.

Quickstart

This quickstart demonstrates basic Express setup with `celebrate` middleware for input validation on a POST route. It validates `req.body` and `req.headers` using Joi schemas and includes the `errors()` middleware for consistent error responses. It also shows how to access the `Joi` instance exported by `celebrate` for custom schema definitions.

import express from 'express';
import bodyParser from 'body-parser';
import { celebrate, Joi, errors, Segments } from 'celebrate';

const app = express();

app.use(bodyParser.json());

app.post('/signup', celebrate({
  [Segments.BODY]: Joi.object().keys({
    name: Joi.string().required().min(3).max(50),
    email: Joi.string().email().required(),
    age: Joi.number().integer().min(18).max(120),
    role: Joi.string().valid('user', 'admin').default('user')
  }),
  [Segments.HEADERS]: Joi.object({
    authorization: Joi.string().required()
  }).unknown(true) // Allow other headers
}), (req, res) => {
  // At this point, req.body and req.headers have been validated and 
  // req.body.role is set to 'user' if not provided.
  console.log('Validated body:', req.body);
  console.log('Validated headers:', req.headers.authorization);
  res.status(200).send('Signup successful!');
});

// Error handling middleware from celebrate
app.use(errors());

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

// Example of accessing the exported Joi instance directly
const myCustomSchema = Joi.object({
  customField: Joi.string().alphanum().min(3).required()
});

// To test, send a POST request to http://localhost:3000/signup 
// with a JSON body like: 
// {"name": "Test User", "email": "test@example.com", "age": 30}
// and an 'Authorization' header. A missing 'name' or 'email' will fail validation.