celebrate

library0.0.1jsnpmunverified

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.

web-framework serialization

npm install celebrate

github ↗package ↗

INSTALL

IMPORT

SIG · CELEBRATE

celebrate

web-frameworkjavascriptv0.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

celebrate

✓ import { celebrate } from 'celebrate';

✗ const celebrate = require('celebrate');

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

Joi

✓ import { Joi } from 'celebrate';

✗ import Joi from 'joi';

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

✓ import { errors } from 'celebrate';

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

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

Segments

✓ import { Segments } from 'celebrate';

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

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

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.

Debug

Known issues

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.

affects: >=15.0.0

breakingThe 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 })`.

affects: >=14.0.0

breakingCelebrate 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.

affects: >=13.0.0

breakingThe `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`.

affects: >=8.0.0 <13.0.0

breakingCelebrate 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.

affects: >=4.0.0

gotchaCelebrate 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.

affects: >=1.0.0

gotchaCelebrate (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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: celebrate is not a function

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

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')

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.

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.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

joirequiredCore 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.

expressrequiredCelebrate 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.

body-parseroptionalRequired for `celebrate` to validate `req.body`. If not used, `req.body` will be `undefined` and validation will not apply.

cookie-parseroptionalRequired for `celebrate` to validate `req.cookies` and `req.signedCookies`.

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/arb/celebrate ↗

packagehttps://www.npmjs.com/package/celebrate ↗