{"id":17083,"library":"celebrate","title":"Celebrate","description":"Celebrate is a robust Express.js middleware designed for integrating Joi validation seamlessly into web applications. It allows developers to define validation schemas for various parts of an incoming request, including `req.params`, `req.headers`, `req.query`, `req.body`, `req.cookies`, and `req.signedCookies`. The library is currently stable at version 15.0.3 and undergoes regular maintenance with notable major version updates introducing breaking changes (e.g., v15, v14, v13, v8, v4, v3, v2). A key differentiator is its formal dependency on `joi`, ensuring a consistent and up-to-date Joi version is always used and also exported for consumer compatibility. It aims to simplify input validation in Express routes, providing a consistent error handling mechanism before any route handler is executed.","status":"active","version":"15.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/arb/celebrate","tags":["javascript","joi","validation","express","middleware","typescript"],"install":[{"cmd":"npm install celebrate","lang":"bash","label":"npm"},{"cmd":"yarn add celebrate","lang":"bash","label":"yarn"},{"cmd":"pnpm add celebrate","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core validation library wrapped by Celebrate. Celebrate explicitly lists Joi as a formal dependency to ensure a predictable and up-to-date version is always used.","package":"joi","optional":false},{"reason":"Celebrate is an Express.js middleware and requires an Express application to function. While not a direct `dependencies` entry in its package.json, it's a fundamental peer dependency.","package":"express","optional":false},{"reason":"Required for `celebrate` to validate `req.body`. If not used, `req.body` will be `undefined` and validation will not apply.","package":"body-parser","optional":true},{"reason":"Required for `celebrate` to validate `req.cookies` and `req.signedCookies`.","package":"cookie-parser","optional":true}],"imports":[{"note":"For ESM modules or TypeScript, use named import. CommonJS applications use `require()`. Ensure `type: module` in `package.json` for ESM.","wrong":"const celebrate = require('celebrate');","symbol":"celebrate","correct":"import { celebrate } from 'celebrate';"},{"note":"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.","wrong":"import Joi from 'joi';","symbol":"Joi","correct":"import { Joi } from 'celebrate';"},{"note":"The `errors()` middleware should be placed after your routes to catch validation errors and format them consistently.","wrong":"const errors = require('celebrate').errors;","symbol":"errors","correct":"import { errors } from 'celebrate';"},{"note":"Used to specify which part of the request object (e.g., `Segments.BODY`, `Segments.QUERY`) the Joi schema applies to.","wrong":"const { Segments } = require('celebrate').Segments;","symbol":"Segments","correct":"import { Segments } from 'celebrate';"}],"quickstart":{"code":"import express from 'express';\nimport bodyParser from 'body-parser';\nimport { celebrate, Joi, errors, Segments } from 'celebrate';\n\nconst app = express();\n\napp.use(bodyParser.json());\n\napp.post('/signup', celebrate({\n  [Segments.BODY]: Joi.object().keys({\n    name: Joi.string().required().min(3).max(50),\n    email: Joi.string().email().required(),\n    age: Joi.number().integer().min(18).max(120),\n    role: Joi.string().valid('user', 'admin').default('user')\n  }),\n  [Segments.HEADERS]: Joi.object({\n    authorization: Joi.string().required()\n  }).unknown(true) // Allow other headers\n}), (req, res) => {\n  // At this point, req.body and req.headers have been validated and \n  // req.body.role is set to 'user' if not provided.\n  console.log('Validated body:', req.body);\n  console.log('Validated headers:', req.headers.authorization);\n  res.status(200).send('Signup successful!');\n});\n\n// Error handling middleware from celebrate\napp.use(errors());\n\napp.listen(3000, () => {\n  console.log('Server running on http://localhost:3000');\n});\n\n// Example of accessing the exported Joi instance directly\nconst myCustomSchema = Joi.object({\n  customField: Joi.string().alphanum().min(3).required()\n});\n\n// To test, send a POST request to http://localhost:3000/signup \n// with a JSON body like: \n// {\"name\": \"Test User\", \"email\": \"test@example.com\", \"age\": 30}\n// and an 'Authorization' header. A missing 'name' or 'email' will fail validation.\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Change `import Joi from 'celebrate'` to `import { Joi } from 'celebrate';` or `const { Joi } = require('celebrate');` for CommonJS.","message":"`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.","severity":"breaking","affected_versions":">=15.0.0"},{"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 })`.","message":"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.","severity":"breaking","affected_versions":">=14.0.0"},{"fix":"Ensure `joi` is updated to a compatible version (v17+). Review error handling and `req.params` schema definitions. Migrate away from `celebrator` if used.","message":"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.","severity":"breaking","affected_versions":">=13.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=8.0.0 <13.0.0"},{"fix":"Upgrade Node.js to version 10 or newer. It is recommended to use an actively maintained Node.js LTS version.","message":"Celebrate dropped support for Node.js versions older than 10.x. This impacts deployment environments and local development setups.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid sending bodies with GET requests. Use `req.query` or `req.params` for data in GET requests and define your schemas accordingly.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ES Modules and TypeScript: `import { celebrate } from 'celebrate';`. For CommonJS: `const { celebrate } = require('celebrate');`. Ensure `package.json` has `\"type\": \"module\"` for ESM.","cause":"Incorrect import statement or mixing CommonJS `require` with ES Modules `import` syntax without proper configuration.","error":"TypeError: celebrate is not a function"},{"fix":"Ensure the client is sending all required fields as defined in your Joi schema. Double-check field names and casing.","cause":"A Joi schema marked a field as `required()` but it was missing from the incoming request payload.","error":"ValidationError: \"someField\" is required"},{"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.","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`.","error":"Cannot read properties of undefined (reading 'json')"},{"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.","cause":"You are attempting to `require()` an ES Module in a CommonJS context, often when `celebrate` (or its dependencies) have transitioned to ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... celebrated.js not supported."}],"ecosystem":"npm","meta_description":null}