Migrate Joi to Zod

Quick Start

Install SchemaShift and run the migration in two commands:

npm install -g schemashift-cli

schemashift migrate ./src -f joi -t zod

This analyzes every file in ./src, rewrites Joi schemas to Zod, updates imports, and creates backup files automatically.

Before & After

import Joi from 'joi';

const userSchema = Joi.object({
  name: Joi.string().required().min(2),
  email: Joi.string().email().required(),
  port: Joi.number().port(),
  role: Joi.string().valid('admin', 'user')
});

import { z } from 'zod';

const userSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  port: z.number().int().min(0).max(65535),
  role: z.enum(['admin', 'user'])
});

type User = z.infer<typeof userSchema>;

Notice how Zod gives you the User type for free — no separate interface to maintain.

Conversion Reference

Complete mapping from Joi methods to their Zod equivalents. SchemaShift handles all of these automatically.

Edge Cases & Gotchas

These Joi patterns have no direct Zod equivalent and require manual attention. SchemaShift generates scaffolding code and inline TODO comments for each one.

• .when() conditionals — Joi's .when() supports conditional schema selection based on sibling fields. Zod has no built-in equivalent. SchemaShift generates .superRefine() scaffolding with the condition logic preserved in comments.
• .with() / .without() — Field dependency rules (e.g., "if field A is present, field B is required") map to .superRefine() with manual field-presence checks in Zod.
• .and() / .nand() / .or() / .xor() — Group constraints on object fields require custom .superRefine() logic. SchemaShift generates the boilerplate with field names preserved.
• Joi.ref() cross-references — Cross-field references like Joi.ref('password') for confirmation fields become .refine() callbacks that access the full object via the path.
• .messages() custom error strings — Joi's centralized .messages() object does not map cleanly. Zod uses inline error strings passed directly to each validation method (e.g., .min(2, { message: "Too short" })).
• .external() async validation — Joi's .external() for async checks becomes .refine(async () => { ... }) in Zod, requiring .parseAsync() instead of .parse() at the call site.

Automated Migration Commands

Preview changes without modifying any files:

schemashift migrate ./src -f joi -t zod --dry-run

Run the full migration with verbose output:

schemashift migrate ./src -f joi -t zod --verbose

Generate a unified diff for code review:

schemashift migrate ./src -f joi -t zod --dry-run --output-diff changes.patch

Migrate with a Git branch for easy rollback:

schemashift migrate ./src -f joi -t zod --git-branch migrate/joi-to-zod

Manual Migration Checklist

After running the automated migration, review these items:

• Search for TODO(schemashift) comments and resolve each one
• Replace Joi.validate(data, schema) calls with schema.parse(data) or schema.safeParse(data)
• Update error handling — Zod throws ZodError instead of returning { error, value }
• Remove the joi package from package.json once all schemas are converted
• Add z.infer<typeof schema> type exports where you previously maintained manual interfaces
• Update form library resolvers (e.g., joiResolver to zodResolver in React Hook Form)
• Replace Joi.ref() cross-references with .refine() callbacks
• Convert .external() async validators and switch to .parseAsync()
• Run your test suite to verify validation behavior is preserved

Frequently Asked Questions

Related Migration Guides