celebrate: Joi validation middleware for Express routes

Why celebrate belongs in an Express request pipeline

celebrate addresses the gap between Express's flexible request handling and the need to reject malformed input before route handlers use it. The README describes it as middleware that wraps Joi and can be applied to a single route or registered globally. That placement suits teams that want request validation to appear beside routing code instead of repeating it inside every controller.

The middleware covers the request locations most often constrained by an HTTP contract. It validates `req.params`, `req.headers`, and `req.query` directly. It can also validate `req.body`, `req.cookies`, and `req.signedCookies`, although those properties must first be populated by `body-parser` or `cookie-parser`. celebrate does not parse bodies or cookies by itself. The parser must run earlier, then celebrate checks the resulting request properties.

The intended users are Express developers who understand middleware ordering and can express their constraints with Joi. celebrate is not a framework-independent schema package and is not a replacement for parser middleware. Its API returns the standard `(req, res, next)` function, keeping it inside Express's routing model. The README states that the project is tested and fully compatible with Express 4 and 5. It says Express 3 likely works, but Express 3 is outside the test matrix because it exposes route parameters as an array rather than an object.

How celebrate maps schemas to request segments

The main entry point is `celebrate(schema, [joiOptions], [opts])`. Its schema is an object whose keys use values exported through `Segments`. Each value contains a Joi schema for the corresponding request property. Only the locations named in the object are validated. Omitting a segment leaves that part of `req` outside the checks performed by that middleware invocation.

When the returned middleware runs, it applies the selected schemas to the corresponding Express request properties. Joi can also transform accepted values. The README's signup example assigns `admin` when no `role` is supplied, so the downstream handler receives the value produced by the schema rather than merely the original input. This is useful for defaults and normalization, but it means a handler is consuming values that validation middleware may have changed.

By default, `joiOptions` is `{ warnings: true }`, and the middleware `opts` default to `{}`. Setting `opts.reqContext` makes the incoming request available to Joi as its validation context and takes precedence over `joiOptions.context`. This supports rules that compare one request segment with another. Setting `opts.mode` controls the validation mode and defaults to `partial`.

The package exports `Joi`, allowing application code to use the Joi instance selected by celebrate. The README explains that Joi is a formal dependency so validation and compilation use a known version and can expose that version to consumers. `package.json` currently declares `joi: 18.x.x`.

Installing celebrate for a protected signup route

The repository identifies the distributed npm package as `celebrate`. The README does not show an installation command, but it links to the package on npm, which is the documented distribution source. The current package metadata requires Node `>=20`, uses ES modules, and exposes its API from `lib/index.js`.

The first real use can follow the README's signup example. This code creates an Express application, loads `body-parser`, and imports celebrate's validation API before defining the route:

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

const app = express();
app.use(BodyParser.json());

`BodyParser.json()` must run before validation because it creates `req.body`. The following route requires a body name, accepts an integer age, defaults the role to `admin`, and requires a token in the query string:

app.post('/signup', celebrate({
  [Segments.BODY]: Joi.object().keys({
    name: Joi.string().required(),
    age: Joi.number().integer(),
    role: Joi.string().default('admin')
  }),
  [Segments.QUERY]: {
    token: Joi.string().token().required()
  }
}), (req, res) => {
  // At this point, req.body has been validated and 
  // req.body.role is equal to req.body.role if provided in the POST or set to 'admin' by joi
});
app.use(errors());

The handler is reached only after both segment schemas succeed. The `errors()` middleware is registered after the route so it can receive errors forwarded during validation. Cookie validation has the same ordering requirement: `cookie-parser` must populate `req.cookies` or `req.signedCookies` before celebrate inspects them.

Global header validation and the cost of shared rules

For a requirement shared across routes, celebrate can be registered with `app.use()`. The README uses a token header as its example, applying the schema before the `/` and `/foo` handlers. Calling `.unknown()` on the headers object permits headers other than `token`, while the named token must exist and match `/abc\d{3}/`:

import express from 'express';
import { celebrate, Joi, errors, Segments } from 'celebrate';
const app = express();

app.use(celebrate({
  [Segments.HEADERS]: Joi.object({
    token: Joi.string().required().regex(/abc\d{3}/)
  }).unknown()
}));
app.get('/', (req, res) => { res.send('hello world'); });
app.get('/foo', (req, res) => { res.send('a foo request'); });
app.use(errors());

Global validation removes repeated setup, but it also makes the rule apply to every request that reaches the middleware. A token required only by administrative routes belongs near those routes. A requirement common to the entire application, such as a particular header, may be appropriate at application scope.

A schema must contain at least one valid segment key. The public API also includes `errors([opts])`, `new CelebrateError([message], [opts])`, `isCelebrateError(err)`, and exported `Modes` and `Segments` values. The README excerpt does not fully document the status-code or response-body contract for `errors()`. Teams that require an exact JSON error format should inspect that API before standardizing their public responses.

Express, Node, Joi, and celebrate version boundaries

The current `package.json` identifies celebrate as version `16.0.0`, an ES module with type declarations at `lib/index.d.ts`. It requires Node 20 or later and uses Express 5 as the development dependency. That engine requirement excludes older Node deployments even though the README states runtime compatibility with both Express 4 and 5.

Joi is not an optional peer dependency. The package declares `joi: 18.x.x`, and celebrate exports its `Joi` value. Applications that build schemas with this export use the same Joi implementation selected for middleware validation. They still need to account for Joi's schema behavior when upgrading.

Published releases listed on the repository page include v13.0.0 on 2020-09-04, v14.0.0 on 2021-04-22, and v15.0.0 on 2021-07-09, while `package.json` is at 16.0.0. Release history alone does not describe what changed between major versions. An upgrade should therefore check Node requirements, Joi schemas, validation options, modes, and the application's handling of Celebrate errors.

The repository is not archived, and its last push was on 2026-09-29. That fact says when repository work occurred, but it does not establish compatibility between an installed version and a given application. Upgrade effort is mainly the work needed to reconcile Node, Joi, middleware behavior, and API response handling.

MIT licensing and a direct Joi alternative

The package metadata declares the MIT license. Its notice must be retained in copies or substantial portions of the distribution. That is a description of the declared license terms, not legal advice about a particular product or service.

The closest architectural alternative is to invoke Joi directly in a route handler or in application-owned middleware. Direct Joi validation keeps schema definition, validation, and consumption close together and gives the application complete control over the response. celebrate instead provides segment selection, a standard middleware signature, Joi option defaults, request-context behavior, and its own error path.

This convenience adds a package between controllers and Joi. It is a poor fit for teams that do not use Joi, need Express 3's route-parameter representation, or prefer not to standardize error handling through `errors()`. It is also unnecessary when a few direct Joi checks are easier to read than a middleware layer. The repository includes `lib/`, `test/`, `utils/`, and TypeScript declarations, but the README does not provide a comparison guide with other validation libraries.

Editorial conclusion

Express teams already using Joi and able to standardize on Node 20 or later can adopt celebrate when middleware-based validation matches their route design. Projects that need direct handler guards, non-Joi schemas, or documented error response controls should verify those requirements first. The repository supports Express 4 and 5, while the current package entry is version 16.0.0 with joi 18.x.x as its declared validation dependency.

Frequently asked questions

Official sources

1. arb/celebrate on GitHub
2. Issues
3. License: MIT
4. README
5. Releases