Fastify Type Provider Zod

Zod compatibility

fastify-type-provider-zod	zod
<=4.x	v3
>=5.x	v4

How to use?

1import type { ZodTypeProvider } from 'fastify-type-provider-zod';
2import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
3import { z } from 'zod/v4';
4
5const app = Fastify();
6
7// Add schema validator and serializer
8app.setValidatorCompiler(validatorCompiler);
9app.setSerializerCompiler(serializerCompiler);
10
11app.withTypeProvider<ZodTypeProvider>().route({
12  method: 'GET',
13  url: '/',
14  // Define your schema
15  schema: {
16    querystring: z.object({
17      name: z.string().min(4),
18    }),
19    response: {
20      200: z.string(),
21    },
22  },
23  handler: (req, res) => {
24    res.send(req.query.name);
25  },
26});
27
28app.listen({ port: 4949 });

You can also pass options to the serializerCompiler function:

1type ZodSerializerCompilerOptions = {
2  replacer?: ReplacerFunction;
3};

1import Fastify from 'fastify';
2import { createSerializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
3
4const app = Fastify();
5
6const replacer = function (key, value) {
7  if (this[key] instanceof Date) {
8    return { _date: value.toISOString() };
9  }
10  return value;
11};
12
13// Create a custom serializer compiler
14const customSerializerCompiler = createSerializerCompiler({ replacer });
15
16// Add schema validator and serializer
17app.setValidatorCompiler(validatorCompiler);
18app.setSerializerCompiler(customSerializerCompiler);
19
20// ...
21
22app.listen({ port: 4949 });

How to use together with @fastify/swagger

1import fastify from 'fastify';
2import fastifySwagger from '@fastify/swagger';
3import fastifySwaggerUI from '@fastify/swagger-ui';
4import { z } from 'zod/v4';
5import type { ZodTypeProvider } from 'fastify-type-provider-zod';
6import {
7  jsonSchemaTransform,
8  createJsonSchemaTransform,
9  serializerCompiler,
10  validatorCompiler,
11} from 'fastify-type-provider-zod';
12
13const app = fastify();
14app.setValidatorCompiler(validatorCompiler);
15app.setSerializerCompiler(serializerCompiler);
16
17app.register(fastifySwagger, {
18  openapi: {
19    info: {
20      title: 'SampleApi',
21      description: 'Sample backend service',
22      version: '1.0.0',
23    },
24    servers: [],
25  },
26  transform: jsonSchemaTransform,
27
28  // You can also create transform with custom skiplist of endpoints that should not be included in the specification:
29  //
30  // transform: createJsonSchemaTransform({
31  //   skipList: [ '/documentation/static/*' ]
32  // })
33});
34
35app.register(fastifySwaggerUI, {
36  routePrefix: '/documentation',
37});
38
39const LOGIN_SCHEMA = z.object({
40  username: z.string().max(32).describe('Some description for username'),
41  password: z.string().max(32),
42});
43
44app.after(() => {
45  app.withTypeProvider<ZodTypeProvider>().route({
46    method: 'POST',
47    url: '/login',
48    schema: { body: LOGIN_SCHEMA },
49    handler: (req, res) => {
50      res.send('ok');
51    },
52  });
53});
54
55async function run() {
56  await app.ready();
57
58  await app.listen({
59    port: 4949,
60  });
61
62  console.log(`Documentation running at http://localhost:4949/documentation`);
63}
64
65run();

Customizing error responses

You can add custom handling of request and response validation errors to your fastify error handler like this:

1import { hasZodFastifySchemaValidationErrors } from 'fastify-type-provider-zod';
2
3fastifyApp.setErrorHandler((err, req, reply) => {
4  if (hasZodFastifySchemaValidationErrors(err)) {
5    return reply.code(400).send({
6      error: 'Response Validation Error',
7      message: "Request doesn't match the schema",
8      statusCode: 400,
9      details: {
10        issues: err.validation,
11        method: req.method,
12        url: req.url,
13      },
14    });
15  }
16
17  if (isResponseSerializationError(err)) {
18    return reply.code(500).send({
19      error: 'Internal Server Error',
20      message: "Response doesn't match the schema",
21      statusCode: 500,
22      details: {
23        issues: err.cause.issues,
24        method: err.method,
25        url: err.url,
26      },
27    });
28  }
29
30  // the rest of the error handler
31});

How to create refs to the schemas?

When provided, this package will automatically create refs using the jsonSchemaTransformObject function. You register the schemas with the global Zod registry and assign them an id. fastifySwagger will then create an OpenAPI document that references the schemas.

The following example creates a ref to the User schema and will include the User schema in the OpenAPI document.

1import fastifySwagger from '@fastify/swagger';
2import fastifySwaggerUI from '@fastify/swagger-ui';
3import fastify from 'fastify';
4import { z } from 'zod/v4';
5import type { ZodTypeProvider } from 'fastify-type-provider-zod';
6import {
7  jsonSchemaTransformObject,
8  jsonSchemaTransform,
9  serializerCompiler,
10  validatorCompiler,
11} from 'fastify-type-provider-zod';
12
13const USER_SCHEMA = z.object({
14  id: z.number().int().positive(),
15  name: z.string().describe('The name of the user'),
16});
17
18z.globalRegistry.add(USER_SCHEMA, { id: 'User' });
19
20const app = fastify();
21app.setValidatorCompiler(validatorCompiler);
22app.setSerializerCompiler(serializerCompiler);
23
24app.register(fastifySwagger, {
25  openapi: {
26    info: {
27      title: 'SampleApi',
28      description: 'Sample backend service',
29      version: '1.0.0',
30    },
31    servers: [],
32  },
33  transform: jsonSchemaTransform,
34  transformObject: jsonSchemaTransformObject,
35});
36
37app.register(fastifySwaggerUI, {
38  routePrefix: '/documentation',
39});
40
41app.after(() => {
42  app.withTypeProvider<ZodTypeProvider>().route({
43    method: 'GET',
44    url: '/users',
45    schema: {
46      response: {
47        200: USER_SCHEMA.array(),
48      },
49    },
50    handler: (req, res) => {
51      res.send([]);
52    },
53  });
54});
55
56async function run() {
57  await app.ready();
58
59  await app.listen({
60    port: 4949,
61  });
62
63  console.log(`Documentation running at http://localhost:4949/documentation`);
64}
65
66run();

How to create a plugin?

1import { z } from 'zod/v4';
2import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
3
4const plugin: FastifyPluginAsyncZod = async function (fastify, _opts) {
5  fastify.route({
6    method: 'GET',
7    url: '/',
8    // Define your schema
9    schema: {
10      querystring: z.object({
11        name: z.string().min(4),
12      }),
13      response: {
14        200: z.string(),
15      },
16    },
17    handler: (req, res) => {
18      res.send(req.query.name);
19    },
20  });
21};