omar-dulaimi/prisma-orpc-generator

⚡ Prisma oRPC Generator

Generate typed oRPC routers, Zod schemas, and docs straight from your Prisma schema.

Prisma v7+, Node 20.19+/22.12+/24.0+, TypeScript ≥ 5.4.

TL;DR: Add the generator to your Prisma schema and run Prisma generate. That’s it.

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

generator orpc {
  provider = "prisma-orpc-generator"
  output   = "./src/generated/orpc"

  // Optional config (booleans are strings)
  schemaLibrary = "zod"
  generateInputValidation  = "true"
  generateOutputValidation = "true"

  // Shield authorization (optional)
  generateShield = "true"
  defaultReadRule = "allow"
  defaultWriteRule = "auth"
}

Create prisma.config.ts to hold your datasource connection (replace the URL for your database or driver adapter):

import { defineConfig } from '@prisma/config';

export default defineConfig({
  schema: './schema.prisma',
  datasource: {
    url: 'file:./dev.db',
  },
});

# generate
npx prisma generate --config prisma.config.ts

📋 Table of Contents

⚡ Quickstart - Get up and running in minutes
🏗️ What Gets Generated - See what files are created
⚙️ Configuration - All available options
🔧 Zod Schemas Generation - Schema validation setup
🛡️ Shield Authorization - Type-safe permissions and rules
🧪 Examples - Working examples to explore
❓ FAQ / Troubleshooting - Common issues and solutions
🧑‍💻 Development - Contributing guidelines
🗺️ Roadmap - Planned features and improvements
📄 License - Licensing information
🙏 Acknowledgements - Credits and thanks
📝 Changelog - Version history and changes

⚡ Quickstart

Click to expand quickstart guide

Prerequisites

Node: 20.19.0+, 22.12.0+, or 24.0.0+ (per Prisma 7 engine support)
Prisma CLI (v7+) in your project
TypeScript ≥ 5.4.0 recommended

Install

The generator itself and the Prisma CLI are build-time only. Everything the generated routers import has to be a runtime dependency of your app: @orpc/server, zod, @prisma/client, and orpc-shield (the generated shield.ts and createRouter.ts import it, and shield generation is on by default; drop it only if you set generateShield = "false").

# npm
npm install @orpc/server orpc-shield zod @prisma/client
npm install -D prisma-orpc-generator prisma

# pnpm
pnpm add @orpc/server orpc-shield zod @prisma/client
pnpm add -D prisma-orpc-generator prisma

# yarn
yarn add @orpc/server orpc-shield zod @prisma/client
yarn add -D prisma-orpc-generator prisma

Serving the routers over HTTP additionally needs a handler package, e.g. @orpc/openapi for the OpenAPI server shown further down.

Add the generator (minimal)

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

generator orpc {
  provider = "prisma-orpc-generator"
  output   = "./src/generated/orpc"
}

Generate

npx prisma generate --config prisma.config.ts

🧩 Compatibility

Click to expand compatibility info - Prisma ORM: v7+ - Node.js minimums for Prisma v7: - 20.19.0+ - 22.12.0+ - 24.0.0+ - Not supported: 16, 17, 18, 19, 21, 23 - TypeScript: ≥ 5.4.0

🏗️ What Gets Generated

Click to expand generated files overview A generated surface mirroring your domain:

src/generated/orpc/
├─ routers/
│  ├─ models/           # per-model routers
│  └─ helpers/          # common utilities
├─ tests/               # generated tests
├─ zod-schemas/         # zod (if enabled)
└─ documentation/       # docs (if enabled)

Explore the example outputs:

Routers: examples/basic/src/generated/orpc/routers
Zod schemas: examples/basic/src/generated/orpc/zod-schemas
Tests: examples/basic/src/generated/orpc/tests
Docs: examples/basic/src/generated/orpc/documentation

🛠️ Usage

Click to expand usage guide - Runs as part of Prisma’s generator pipeline. - Default output directory is `./src/generated/orpc` (configurable via the generator block). - Import the generated code into your server/app. See the runnable example server in [examples/basic/src/server.ts](examples/basic/src/server.ts).

Tip: Browse the example’s generated root for real structure: examples/basic/src/generated/orpc.

⚙️ Configuration

Click to expand configuration options Where configuration lives - Inside your generator block in [schema.prisma](examples/basic/schema.prisma) - Booleans are strings: "true"/"false"; numbers as strings are supported

Validated against src/config/schema.ts. Below are the most commonly used options.

Core options

Option	Type	Default	Values	Description
output	string	./src/generated/orpc	any	Directory for generated oRPC artifacts
schemaLibrary	enum	"zod"	zod	Schema validation library
generateInputValidation	boolean (string)	"true"	"true", "false"	Emit Zod validation for inputs
generateOutputValidation	boolean (string)	"true"	"true", "false"	Emit Zod validation for outputs
strictValidation	boolean (string)	"true"	"true", "false"	Stricter Zod shapes for safety
zodSchemasOutputPath	string	./zod-schemas	any	Relative path (under output) for Zod files
externalZodImportPath	string	./zod-schemas	any	Module/path used when importing Zod schemas
zodDateTimeStrategy	enum	"coerce"	"date", "coerce", "isoString"	How DateTime fields are modeled in Zod
zodConfigPath	string	none	any	Path to custom zod.config.json file (relative to schema or absolute)

Operational options

Option	Type	Default	Values	Description
generateModelActions	string list	all	see note	Comma-separated actions to emit (see note below)
showModelNameInProcedure	boolean (string)	"true"	"true", "false"	Prefix procedures with model name
enableSoftDeletes	boolean (string)	"false"	"true", "false"	Add soft-delete semantics where applicable
generateRelationResolvers	boolean (string)	"true"	"true", "false"	Emit helpers to resolve relations
wrapResponses	boolean (string)	"false"	"true", "false"	Wrap handler results in an envelope

DX and formatting

Option	Type	Default	Values	Description
useBarrelExports	boolean (string)	"true"	"true", "false"	Generate index.ts barrel exports
codeStyle	enum	"prettier"	"prettier", "none"	Format generated code with Prettier
generateDocumentation	boolean (string)	"false"	"true", "false"	Generate API documentation
generateTests	boolean (string)	"false"	"true", "false"	Generate test files
enableDebugLogging	boolean (string)	"false"	"true", "false"	Extra logs during generation

Runtime and integration

Option	Type	Default	Values	Description
prismaClientPath	string	@prisma/client	any	Import path for PrismaClient
contextPath	string	""	any	Optional path to your app's Context module
serverPort	number (string)	3000	any	Port used by optional docs/server helpers
apiPrefix	string	""	any	Prefix used by optional docs/server helpers
apiTitle	string	Generated API	any	API title for documentation
apiDescription	string	Auto-generated API from Prisma schema	any	API description for documentation
apiVersion	string	1.0.0	any	API version for documentation

Shield / Authorization

Option	Type	Default	Values	Description
generateShield	boolean (string)	"true"	"true", "false"	Enable shield generation
shieldPath	string	none	any	Path to custom shield file (absolute, relative to project root, relative to output dir, or module specifier)
defaultReadRule	enum	"allow"	"allow", "deny", "auth"	Default rule for read operations
defaultWriteRule	enum	"auth"	"auth", "deny", "allow"	Default rule for write operations
denyErrorCode	string	"FORBIDDEN"	any	Error code for denied access
debug	boolean (string)	"false"	"true", "false"	Enable debug logging
allowExternalErrors	boolean (string)	"false"	"true", "false"	Allow detailed error messages from shields
Notes

generateModelActions supports: create, createMany, findFirst, findFirstOrThrow, findMany, findUnique, findUniqueOrThrow, update, updateMany, upsert, delete, deleteMany, aggregate, groupBy, count, findRaw, aggregateRaw.
Booleans are strings in Prisma generator config: use "true" or "false".
The full, authoritative shape lives in src/config/schema.ts.

Example: focused configuration with Zod and docs

generator orpc {
  provider = "prisma-orpc-generator"
  output   = "./src/generated/orpc"

  schemaLibrary             = "zod"
  zodDateTimeStrategy       = "coerce"
  generateInputValidation   = "true"
  generateOutputValidation  = "true"
  generateDocumentation     = "true"
  useBarrelExports          = "true"
  codeStyle                 = "prettier"
}

🔧 Zod Schemas Generation

Click to expand zod schemas info

This generator leverages prisma-zod-generator to create Zod schemas from your Prisma models. Here's how the process works:

Generation Process

Automatic Integration: When schemaLibrary = "zod" is set, the generator automatically calls prisma-zod-generator
Configuration Management: Creates a zod.config.json file with optimized settings for oRPC usage
Schema Output: Generates Zod schemas in the zod-schemas/ subdirectory of your output path
Import Integration: Generated oRPC routers automatically import and use these schemas for validation

Configuration File

The generator creates a minimal zod.config.json file:

{
  "mode": "full",
  "output": "./zod-schemas"
}

Additional settings are only added when they differ from defaults:

{
  "mode": "full", 
  "output": "./zod-schemas",
  "dateTimeStrategy": "date"
}

DateTime Handling Strategy

The zodDateTimeStrategy option controls how Prisma DateTime fields are modeled in Zod schemas:

Strategy	Zod Schema	Description	prisma-zod-generator equivalent
`"coerce"` (default)	`z.coerce.date()`	Automatically converts strings/numbers to Date objects	`dateTimeStrategy: "coerce"`
`"date"`	`z.date()`	Requires actual Date objects, no conversion	`dateTimeStrategy: "date"`
`"isoString"`	`z.string().regex(ISO).transform()`	Validates ISO string format, transforms to Date	`dateTimeStrategy: "isoString"`

Custom Zod Configuration

For advanced use cases, you can provide your own zod.config.json:

generator orpc {
  provider = "prisma-orpc-generator"
  output   = "./src/generated/orpc"
  
  zodConfigPath = "./custom-zod.config.json"  // Path to your config file
}

When zodConfigPath is specified:

The generator uses your existing configuration
oRPC-specific settings are passed as generator options instead of modifying the config file
Your custom configuration takes precedence

File Structure

Generated Zod schemas follow this structure:

src/generated/orpc/
├─ zod-schemas/
│  ├─ index.ts           # Barrel exports
│  ├─ objects/           # Model schemas
│  │  ├─ UserSchema.ts
│  │  └─ PostSchema.ts
│  └─ inputTypeSchemas/  # Input validation schemas
│     ├─ UserCreateInput.ts
│     └─ UserUpdateInput.ts
└─ routers/              # oRPC routers (import from ../zod-schemas)

🛡️ Shield Authorization

Click to expand shield authorization guide

The generator can automatically generate orpc-shield configurations for type-safe authorization. Shield provides declarative rules, composable operators, and path-based permissions.

Shield Configuration

Add shield options to your generator config:

generator orpc {
  provider = "prisma-orpc-generator"
  output   = "./src/generated/orpc"

  // Enable shield generation
  generateShield = "true"

  // Option 1: Auto-generate shield rules
  defaultReadRule  = "allow"  // "allow", "deny", "auth"
  defaultWriteRule = "auth"   // "auth", "deny"

  // Option 2: Use custom shield file (relative to output dir)
  // shieldPath = "../auth/my-custom-shield"

  // Error handling
  denyErrorCode = "FORBIDDEN"
  debug = "false"
}

What Gets Generated

Shield generation creates:

src/generated/orpc/
├─ shield.ts              # Shield rules and permissions (auto-generated)
├─ routers/
│  ├─ index.ts           # App router with shield exports
│  └─ helpers/
│     └─ createRouter.ts # Base router with shield middleware integration

When shieldPath is provided: The generator skips auto-generation and dynamically integrates your custom shield file into the generated middleware chain.

Dynamic Shield Path Resolution ✨

The generator now features smart dynamic path resolution for shield files. When you specify a shieldPath, the generator automatically:

✅ Resolves relative paths from your project structure
✅ Handles different output directory layouts
✅ Integrates shield middleware using the proper oRPC pattern
✅ Generates correct import paths regardless of nesting depth
✅ Applies middleware to all generated procedures through inheritance

Example Generated Integration:

// In src/generated/orpc/routers/helpers/createRouter.ts
import { permissions } from '../../../../custom-shield';
export const or = os.$context<Context>().use(permissions);

Using Custom Shield Files

For advanced use cases, you can provide your own shield file instead of auto-generation:

generator orpc {
  provider = "prisma-orpc-generator"
  output   = "./src/generated/orpc"

  generateShield = "true"
  shieldPath = "../../src/custom-shield"  // Dynamically resolved!
}

Supported Path Formats:

Relative paths: "../../src/auth/shield"
Project root relative: "src/auth/shield"
Absolute paths: "/absolute/path/to/shield"

Your custom shield file should export a permissions object:

// src/custom-shield.ts
import { rule, allow, deny, shield, or } from 'orpc-shield';
import type { Context } from '../generated/orpc/routers/helpers/createRouter';

const isAuthenticated = rule<Context>()(({ ctx }) => !!ctx.user);
const isAdmin = rule<Context>()(({ ctx }) => ctx.user?.role === 'admin');
const isOwner = rule<Context>()(({ ctx, input }) => {
  return ctx.user?.id === (input as any)?.userId;
});

export const permissions = shield<Context>({
  user: {
    userFindMany: allow,           // Match generated procedure names
    userCreate: isAuthenticated,   
    userUpdate: isAuthenticated,
    userDelete: or(isAdmin, isOwner),
    userDeleteMany: deny,          // Explicitly deny dangerous operations
  },
  post: {
    postFindMany: allow,
    postCreate: isAuthenticated,
    postUpdate: isAuthenticated,
    postDelete: isAuthenticated,
  },
}, {
  denyErrorCode: 'FORBIDDEN',      // Maps to HTTP 403
  debug: true,                     // Enable debug logging
  allowExternalErrors: true,       // Allow detailed error messages
});

Important: Shield procedure names should match your generated router names (e.g., userCreate, postFindMany).

Note: When using shieldPath, the generator will skip auto-generation and use your custom shield file instead.

Generated Shield Rules

The generator creates rules based on your Prisma models:

// Built-in rules (generated automatically)
const isAuthenticated = rule<Context>()(({ ctx }) => !!ctx.user);

// Example custom rules (user-defined)
const isAdmin = rule<Context>()(({ ctx }) => ctx.user?.role === 'admin');

// Model-specific rules (generated based on config)
const canReadUser = allow;           // Read operations: allow
const canWriteUser = isAuthenticated; // Write operations: require auth

// Shield configuration
export const permissions = shield<Context>({
  user: {
    list: canReadUser,
    findById: canReadUser,
    create: canWriteUser,
    update: canWriteUser,
    delete: canWriteUser,
  },
  post: {
    list: allow,
    create: isAuthenticated,
    update: isAuthenticated,
  },
});

Using Shield in Your Server

Import and use the generated shield:

import { appRouter, permissions } from './generated/orpc/routers';

// Apply shield at server level
const server = createServer(appRouter, {
  // Shield is applied via middleware
  middleware: [permissions]
});

// Or use with oRPC handlers
import { OpenAPIHandler } from '@orpc/openapi';

const handler = new OpenAPIHandler(appRouter, {
  // Shield permissions are automatically applied
  interceptors: [/* your interceptors */]
});

Context Requirements

Shield rules expect a Context with user information:

interface Context {
  prisma: PrismaClient;
  user?: {
    id: string;
    email?: string;
    name?: string;
    roles?: string[];
    permissions?: string[];
  };
}

Customization

Override default rules by modifying the generated shield.ts:

// Custom rule for post ownership
const isPostOwner = rule<Context>()(({ ctx, input }) => {
  return ctx.user?.id === (input as any)?.authorId;
});

// Use in shield config
const permissions = shield<Context>({
  post: {
    update: and(isAuthenticated, isPostOwner), // Auth + ownership
    delete: or(isAdmin, isPostOwner),          // Admin or owner
  },
});

Shield Options

Option	Type	Default	Values	Description
generateShield	boolean (string)	"true"	"true", "false"	Enable shield generation
shieldPath	string	none	any	Path to custom shield file (absolute, relative to project root, relative to output dir, or module specifier)
defaultReadRule	enum	"allow"	"allow", "deny", "auth"	Default rule for read operations
defaultWriteRule	enum	"auth"	"auth", "deny", "allow"	Default rule for write operations
denyErrorCode	string	"FORBIDDEN"	any	Error code for denied access
debug	boolean (string)	"false"	"true", "false"	Enable debug logging
allowExternalErrors	boolean (string)	"false"	"true", "false"	Allow detailed error messages from shields

🧪 Examples

Click to expand examples Run the repo example end-to-end ```bash npm run example:basic ```

What it does

Builds the generator
Generates Prisma artifacts
Seeds a local DB
Starts a small server using the generated routers/schemas

Notable files

Server: examples/basic/src/server.ts
Seed: examples/basic/src/seed.ts
Lib utilities: examples/basic/src/lib
Example scripts: examples/basic/package.json

❓ FAQ / Troubleshooting

Click to expand FAQ and troubleshooting Prisma version mismatch - Symptom: generator fails or types not aligned - Action: ensure Prisma v7+ in dev deps and runtime - `npm i -D prisma @prisma/client` - Regenerate: `npx prisma generate --config prisma.config.ts`

Node version or ESM issues

Symptom: runtime errors about module type or syntax
Action: use Node 20.19.0+, 22.12.0+, or 24.0.0+; align package type with your build, then rebuild npm run build

Generated path is unexpected

Symptom: files not where you expect
Action: verify your generator output path and config; compare with examples/basic/src/generated/orpc

Schema/config validation failures

Symptom: errors referencing invalid options
Action: check inputs against src/config/schema.ts; fix paths/booleans; re-run generation

Docs not emitted

Symptom: documentation folder missing
Action: set generateDocumentation = "true" and inspect src/generators/documentation-generator.ts

Shield path resolution errors

Symptom: "Cannot find module" errors for shield imports
Action: verify shieldPath points to correct file; check file exports permissions object; ensure path is relative to project root or absolute
Note: generator now handles dynamic path resolution automatically for common directory structures

🧑‍💻 Development (Contributing)

Click to expand development guide Repo quicklinks - Source: [src/](src) - Generators: [src/generators/](src/generators) - Entry point: [src/bin.ts](src/bin.ts) - Public exports: [src/index.ts](src/index.ts) - Tests: [tests/](tests)

Local dev loop

npm run dev         # watch build
npm run build       # one-off build
npm run lint        # lint
npm run lint:fix    # lint + fix
npm run format      # prettier
npm run typecheck   # types only

Local development (monorepo) provider example

generator orpc {
  provider = "../../lib/bin.js" // relative path to built generator
  output   = "./src/generated/orpc"
}

Testing

npm test               # unit/integration
npm run test:watch     # watch
npm run test:e2e       # Prisma-backed CRUD
npm run test:coverage  # coverage

Conventions

Conventional Commits
Ensure npm run build and npm run typecheck pass before PR
Update README.md if flags/outputs change

🗺️ Roadmap

✅ Integration with oRPC Shield - Built-in authorization with dynamic path resolution
Schema-based Auth Configuration - Define authorization rules directly in Prisma schema, JSON, or TypeScript config files
Plugin hooks for custom emitters
Config discovery and overrides

📄 License

License: MIT. See the LICENSE file.
Copyright © 2025 Omar Dulaimi.

🙏 Acknowledgements

Prisma and its ecosystem
oRPC community and patterns
Zod for runtime validation
TypeScript tooling
Vitest and contributors

📝 Changelog

See CHANGELOG.md

Made with ❤️ by Omar Dulaimi