Migrate Zod to Superstruct

Quick Start

Convert your Zod schemas to Superstruct automatically:

npx schemashift-cli migrate ./src --from zod --to superstruct

Before & After

// schemas/order.ts
import { z } from 'zod';

const OrderSchema = z.object({
  id: z.string(),
  amount: z.number().int().positive(),
  currency: z.enum(['USD', 'EUR', 'GBP']),
  status: z.enum(['pending', 'paid', 'shipped']),
  items: z.array(z.object({
    name: z.string(),
    quantity: z.number().int(),
    price: z.number(),
  })),
  notes: z.string().optional(),
  discount: z.number().nullable(),
  createdAt: z.date(),
});

type Order = z.infer<typeof OrderSchema>;

const validated = OrderSchema.parse(input);

const PartialOrder = OrderSchema.partial();

const ItemSchema = OrderSchema.shape.items;

// schemas/order.ts
import {
  object, string, number, integer, enums,
  array, optional, nullable, date, partial,
  type Infer,
} from 'superstruct';
import { refine } from 'superstruct';

const OrderSchema = object({
  id: string(),
  amount: refine(integer(), 'positive', (v) => v > 0),
  currency: enums(['USD', 'EUR', 'GBP']),
  status: enums(['pending', 'paid', 'shipped']),
  items: array(object({
    name: string(),
    quantity: integer(),
    price: number(),
  })),
  notes: optional(string()),
  discount: nullable(number()),
  createdAt: date(),
});

type Order = Infer<typeof OrderSchema>;

const validated = create(input, OrderSchema);

const PartialOrder = partial(OrderSchema);

/* TODO(schemashift): Superstruct does not support
   .shape access. Extract the items struct separately. */

Conversion Reference

Edge Cases & Gotchas

• No discriminatedUnion: Superstruct does not have discriminatedUnion(). Use union() which tests each variant sequentially. For performance-sensitive code with many variants, consider keeping a manual discriminator check before validation.
• .transform() → coerce(): Zod's .transform() maps to Superstruct's coerce(). The semantics differ: coerce(string(), unknown(), (v) => String(v)) applies the coercion before validation, while Zod's transform runs after. This can change behavior for invalid inputs.
• No .brand(): Superstruct has no branded type support. If you use Zod's .brand() for nominal typing, you will need TypeScript's manual branding pattern or define() with a custom validator.
• Bare function imports: Superstruct uses direct function imports rather than a namespace. Instead of z.string(), you import string directly: import { string, number, object } from 'superstruct'. This can create naming conflicts with built-in JavaScript constructors.
• Argument order for create(): Zod uses schema.parse(input) as a method call. Superstruct uses create(input, schema) as a standalone function with reversed argument order. This affects every validation call site in your codebase.
• No .shape access: Zod allows Schema.shape.fieldName to access individual field schemas. Superstruct does not expose this API. Extract field structs as separate variables instead.

Automated Migration with SchemaShift

# Dry run to preview changes
npx schemashift-cli migrate ./src --from zod --to superstruct --dry-run

# Run the migration
npx schemashift-cli migrate ./src --from zod --to superstruct

# With cross-file resolution
npx schemashift-cli migrate ./src --from zod --to superstruct --cross-file --verbose

# Generate a diff for code review
npx schemashift-cli migrate ./src --from zod --to superstruct --dry-run --output-diff changes.patch

Manual Migration Checklist

• Replace import { z } from 'zod' with individual Superstruct imports
• Convert all z.object({}) to object({})
• Convert all z.string() / z.number() to bare string() / number()
• Convert z.enum([]) to enums([])
• Convert .optional() to optional(X) wrapper
• Convert .nullable() to nullable(X) wrapper
• Replace z.number().int() with integer()
• Convert .refine(fn) to refine(struct, name, fn)
• Replace .transform() with coerce()
• Convert schema.parse(input) to create(input, schema)
• Replace z.infer<typeof X> with Infer<typeof X>
• Handle discriminatedUnion manually with union()
• Extract .shape accesses into standalone struct variables
• Update package.json: add superstruct, remove zod
• Run your test suite to verify behavior

Frequently Asked Questions

Related Guides