@libar-dev/zod-convex

The only Zod-to-Convex bridge with build-time code generation — eliminating Zod from your production bundle and reducing runtime memory by 75-90% to safely operate within Convex's 64MB limit.

The Problem

Convex functions run in a 64MB memory runtime. Zod v4 alone consumes ~40-50MB at runtime, leaving almost no headroom for your application. Complex schemas push memory usage to 60-65MB, causing crashes in production. Deeply nested schemas also trigger TS2589 ("Type instantiation is excessively deep") errors.

The Solution

Build-time code generation that converts your Zod schemas into pure Convex validators — zero Zod dependency at runtime:

Zod Schema (development)
    ↓ zod-convex-core (conversion)
Runtime Convex Validator
    ↓ zod-convex-gen (serialization)
Pure TypeScript Code (production)
    ↓
Zero Zod dependency at runtime

Packages

                    zod-convex-ids (leaf)
                           │
                           ▼
                    zod-convex-core
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    zod-convex-tables  zod-convex-codecs  zod-convex-gen (CLI)
                           │
                           ▼
                    zod-convex-builders

Package	Purpose	npm
@libar-dev/zod-convex-core	Core conversion engine
@libar-dev/zod-convex-ids	Type-safe ID validation
@libar-dev/zod-convex-tables	Table schema utilities
@libar-dev/zod-convex-codecs	Bidirectional encoding
@libar-dev/zod-convex-gen	Build-time validator generator
@libar-dev/zod-convex-builders	Auth-aware function builders
@libar-dev/eslint-plugin-zod-convex	ESLint rules for hybrid validation

Which Packages Do I Need?

┌─────────────────────────────────────────────────────────────────┐
│ What's your use case?                                           │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   Development/          Production/           Full-Featured
   Prototyping           Optimization          Application
        │                     │                     │
        ▼                     ▼                     ▼
   core only              core + gen            builders + gen
   (runtime)              (build-time)          + ids (optional)

Need	Packages	Install
Basic Zod-to-Convex conversion	core	npm install @libar-dev/zod-convex-core zod@^4
Type-safe table ID references	ids	npm install @libar-dev/zod-convex-ids zod@^4
Table schema utilities	tables	npm install @libar-dev/zod-convex-tables zod@^4
Date/custom type encoding	codecs	npm install @libar-dev/zod-convex-codecs zod@^4
Build-time optimization (90% memory reduction)	gen	npm install -D @libar-dev/zod-convex-gen tsx
Auth-aware function builders	builders	npm install @libar-dev/zod-convex-builders zod@^4

Quick Start

1. Development (Runtime Conversion)

npm install @libar-dev/zod-convex-core zod@^4

import { zodToConvex } from '@libar-dev/zod-convex-core';
import { z } from 'zod';
import { mutation } from './_generated/server';

const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
}).strict();

export const createUser = mutation({
  args: zodToConvex(CreateUserSchema),
  handler: async (ctx, args) => {
    return await ctx.db.insert('users', args);
  },
});

2. Production (Build-Time Generation)

npm install @libar-dev/zod-convex-core zod@^4
npm install -D @libar-dev/zod-convex-gen tsx

Define your schema with a type alias:

// src/table-schemas/users.ts
export const UsersTableSchema = z.object({
  name: z.string(),
  email: z.string().email(),
}).strict();

export type User = z.infer<typeof UsersTableSchema>;

Generate validators and use them with zero Zod at runtime:

npx zod-convex-gen

// convex/users.ts
import type { User } from '../src/table-schemas/users';
import { usersFields } from './generatedValidators/users';

export const createUser = mutation({
  args: usersFields,  // Pure Convex validators — no Zod
  handler: async (ctx, args: User) => {
    return await ctx.db.insert('users', args);
  },
});

Memory Impact

Configuration	Runtime Memory	Production Ready?
Native v.* only	~5-10 MB	Yes
Zod runtime (core only)	~55-62 MB	Risk (near 64MB limit)
Build-time generation (gen)	~10-15 MB	Yes

Version Compatibility

• Zod: ^4.1.0
• Convex: >=1.30.0 <2.0.0
• TypeScript: >=5.5.0

Documentation

• Getting Started Guide
• Package Combinations
• TS2589 Prevention Guide
• Generator Architecture

Security

See SECURITY.md for vulnerability reporting and security best practices.

License

MIT