fastify-zod-validate

A type-safe validation plugin for Fastify 4.x and Zod, arguably the best TypeScript-first validation library.

Install

npm i -S fastify-zod-validate

Features

• Opt-in schema validation for each Fastify route via fastify.withTypeProvider()
• Customize schema validation error when registering the plugin

Assumptions

• Fastify 4.x and Zod 3.x are already installed in your project

Usage

Thefastify-zod-validate plugin decorates the fastify instance with a withTypeProvider function, which can be used to compile and validate the fastify schemas (comprising HTTP body, path parameters, query parameters, headers and more) using the zod library. You can import the plugin using a default import:

1import fastifyZodValidate from 'fastify-zod-validate'

• Define your schemas using zod:

1import { z } from 'zod'
2
3export const UserBody = z.object({
4  username: z.string().min(5).max(10),
5  balance: z.number().min(1000),
6}).strict()
7export type UserBody = z.infer<typeof UserBody>
8
9export const UserPathParams = z.object({
10  userID: z.string().min(4).max(4),
11}).strict()
12export type UserPathParams = z.infer<typeof UserPathParams>

• Define your fastify router with type-safe schema validation built-in:

1import { FastifyPluginCallback } from 'fastify'
2
3export const zodValidateRouter: FastifyPluginCallback = (fastify, options, next) => {
4  fastify.withTypeProvider().route({
5    method: 'POST',
6    url: '/user/:userID',
7    schema: {
8      body: UserBody,
9      params: UserPathParams,
10    },
11    handler: async (request, reply) => {
12      // no casting or @ts-ignore required
13      const { body, params } = request
14      const { userID } = params
15  
16      await reply.status(200).send({
17        data: {
18          message: `OK user with ID ${userID}`,
19          body,
20        },
21      })
22    }
23  })
24
25  next()
26}

• Register the plugin and setup your fastify server:

1import fastifyZodValidate from 'fastify-zod-validate'
2import Fastify from 'fastify'
3
4export async function setupServer() {
5  const server = Fastify()
6
7  // register the plugin
8  server.register(fastifyZodValidate, {
9    // optional custom validation error handler
10    handleValidatorError: (error, data) => {
11      const validationError = new Error('Unprocessable Entity - Custom Zod Validation Error')
12
13      // @ts-ignore
14      validationError.statusCode = 422
15      return { error: validationError }
16    },
17  })
18
19  // register the router
20  server.register(zodValidateRouter, { prefix: 'route' })
21
22  await server.ready()
23  return server
24}

• Start your fastify server:

1async function main() {
2  const server = await setupServer()
3  server.listen({ port: 3000 })
4}
5
6main()

• See validation in action:

  The following HTTP request

  1{
  2curl -0 -X POST http://localhost:3000/route/user/1234 \
  3-H "Content-Type: application/json; charset=utf-8" \
  4-H "X-User: user" \
  5--data-binary @- << EOF
  6{
  7  "username": "invalid, and checked",
  8  "balance": -1
  9}
  10EOF
  11} | jq '.'

  will be rejected with the following error

  {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Unprocessable Entity - Custom Zod Validation Error"
  }
  

We encourage you to take a look at the __tests__ folder for a more complete example.

---

🚀 Build and Test package

This package is built using TypeScript, so the source needs to be converted in JavaScript before being usable by the users. This can be achieved by using TypeScript directly:

1npm run build

We run tests via Jest:

1npm run test

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. The code is short and tested, so you should feel quite comfortable working on it. If you have any doubt or suggestion, please open an issue.

⚠️ Issues

Chances are the problem you have bumped into have already been discussed and solved in the past. Please take a look at the issues (both the closed ones and the comments to the open ones) before opening a new issue.

🦄 Show your support

Give a ⭐️ if this project helped or inspired you! In the future, I might consider offering premium support to Github Sponsors.

👤 Authors

• Alberto Schiabel
  • Github: @jkomyno
  • Twitter: @jkomyno

📝 License

Built with ❤️ by Alberto Schiabel.
This project is MIT licensed.