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.