Zodipus

Zodipus

Type-safe Zod schema generator for Prisma with composable Query Engine.

When to Apply

• User mentions "zodipus" anywhere in conversation
• User wants Zod schemas generated from Prisma
• User needs runtime validation for Prisma queries
• User asks about type-safe query builders
• User has Prisma + Zod integration questions
• User mentions "prisma-zod" or similar terms

Quick Routing

User Intent	Skill
Install, setup, configure generator	zodipus-setup
Query engine, createRegistry, type-safe queries	zodipus-query-engine
JSON fields, @zodSchema, custom schemas	zodipus-custom-schemas
Errors, validation failed, not working	zodipus-troubleshooting
Migrate from other generators	zodipus-migration

Core Concepts

1. Generator

Zodipus is a Prisma generator that outputs Zod schemas:

generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

2. Clean Schemas

Generated schemas contain scalar fields only (no relations). This keeps validation fast and focused:

// Generated UserSchema validates: id, email, name, role, createdAt, updatedAt
// Does NOT include: posts, comments, profile (relations)
const user = UserSchema.parse(data);

3. Query Engine

Build composable queries with automatic validation:

import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

const registry = createRegistry({ models, relations: modelRelations });
const userQuery = registry.createQuery('user');

const query = userQuery({
  select: { id: true, email: true },
  posts: { select: { title: true } }
});

const result = query.parse(await prisma.user.findFirst(query.query));
// Fully typed: { id: string; email: string; posts: { title: string }[] }

4. Custom JSON Schemas

Type Prisma JSON fields with @zodSchema:

model Post {
  /// @zodSchema PostMetadataSchema
  metadata Json?
}

Minimal Working Example

Step 1: Install

npm install zodipus zod

Step 2: Configure

generator client {
  provider = "prisma-client-js"
}

generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

model User {
  id    String @id @default(cuid())
  email String @unique
  name  String?
  posts Post[]
}

model Post {
  id       String  @id @default(cuid())
  title    String
  author   User    @relation(fields: [authorId], references: [id])
  authorId String
}

Step 3: Generate

npx prisma generate

Step 4: Use

import { UserSchema, PostSchema } from './generated';
import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

// Direct validation
const user = UserSchema.parse(userData);

// Query with validation
const registry = createRegistry({ models, relations: modelRelations });
const query = registry.createQuery('user')({
  select: { id: true, email: true, name: true }
});

const users = await prisma.user.findMany(query.query);
const validated = query.array().parse(users);

Generated Files

After running prisma generate, Zodipus creates:

File	Contents
enums.ts	Prisma enums as Zod schemas
models.ts	Clean model schemas (no relations)
custom-schemas.ts	Placeholder for @zodSchema definitions
generated-relations.ts	Relation metadata for Query Engine
generated-index.ts	Re-exports and convenience exports

Priority Reference

Priority	Feature	When to Use
Critical	UserSchema.parse()	Validate any model data
Critical	createRegistry()	Set up Query Engine
High	query.array().parse()	Validate findMany results
High	query.safeParse()	Handle errors without throwing
Medium	@zodSchema annotation	Type JSON fields
Medium	relationDepth config	Deep nested queries
Low	CLI inspect command	Debug schema issues

Quick Reference

See references/QUICK-REFERENCE.md for a complete cheat sheet.