@antislop/zero-lucid-generator

Generate Zero schemas directly from your Lucid ORM models — no manual schema duplication.

Inspired by drizzle-zero and prisma-zero.

---

How it works

@antislop/zero-lucid-generator scans your Lucid model files, introspects their column and relation definitions at runtime, infers TypeScript types via ts-morph, and writes a typed Zero schema file you can import directly into your app.

---

Installation

npm add -D @antislop/zero-lucid-generator

@antislop/zero-lucid-generator is a dev-time generator. You only need it during development to regenerate the schema when models change.

---

Setup

1. Create a config file

Create lucid-zero.config.ts at the root of your project:

import type { Config } from '@antislop/zero-lucid-generator'

const config: Config = {
  modelsSourcePath: './app/models',
}

export default config

2. Run the generator

npx lucid-zero generate

This writes zero-schema.gen.ts next to your config file.

3. Import the schema

import { schema, zql } from './zero-schema.gen.js'

---

Config options

Option	Type	Default	Description
modelsSourcePath	string	required	Path to your models directory, relative to the config file
output	string	zero-schema.gen.ts	Output file path, relative to the config file
format	boolean	false	Format the output with oxfmt (must be installed). Respects your .oxfmtrc.json.
excludeModels	LucidModel[]	[]	Models to exclude from the generated schema
columnTypes	Record<string, Record<string, string>>	{}	Override the inferred Zero type for specific columns

Formatting with oxfmt

Set format: true to have the generated file automatically formatted on every run:

const config: Config = {
  modelsSourcePath: './app/models',
  format: true,
}

Install oxfmt in your project:

npm add -D oxfmt

The formatter picks up your .oxfmtrc.json / oxfmt.config.ts automatically, so the output will always match what your own format scripts produce.

---

CLI options

lucid-zero generate [options]

Options:
  -c, --config <path>     Path to config file     (default: lucid-zero.config.ts)
  -t, --tsconfig <path>   Path to tsconfig.json   (default: tsconfig.json next to config)

---

Column type inference

@antislop/zero-lucid-generator maps TypeScript types to Zero types automatically:

TypeScript type	Zero type
string	string()
number	number()
boolean	boolean()
DateTime / Date	number() (Unix ms)
object / unknown / any	json()
T | null or T | undefined	.optional()

When inference isn't accurate — for example a JSON column with a known shape — use columnTypes:

import type { Config } from '@antislop/zero-lucid-generator'
import Session from "#models/session";

const config: Config = {
  modelsSourcePath: './app/models',
  columnTypes: {
    Issue: {
      // metadata is typed as `unknown` but has a known shape
      metadata: 'json<{ priority: number; labels: string[] }>()',
    },
    User: {
      // role is stored as a string enum
      role: 'enumeration<"admin" | "member" | "viewer">()',
    },
  },
  excludeModels: [Session],
}

export default config

Valid Zero base types: string, number, boolean, json, enumeration.

---

Example output

// zero-schema.gen.ts (auto-generated — do not edit)

import {
  createBuilder,
  createSchema,
  number,
  relationships,
  string,
  table,
} from "@rocicorp/zero";

export const users = table("users")
  .columns({
    id: number(),
    name: string(),
    email: string(),
  })
  .primaryKey("id");

export const posts = table("posts")
  .columns({
    id: number(),
    userId: number().from('user_id'),
    title: string(),
    body: string().optional(),
  })
  .primaryKey("id");

export const usersRelationships = relationships(users, ({ many }) => ({
  posts: many({
    sourceField: ["id"],
    destField: ["userId"],
    destSchema: posts,
  }),
}));

export const schema = createSchema({
  tables: [users, posts],
  relationships: [usersRelationships],
});

export type Schema = typeof schema;

export const zql = createBuilder(schema);

Supported relation types

Lucid relation	Zero mapping
hasOne	one(...)
hasMany	many(...)
belongsTo	one(...)
manyToMany	many([...chain]) via pivot table
hasManyThrough	many([...chain])

Relations pointing to a model not found in modelsSourcePath are skipped with a warning.

---

Automating regeneration

Add a script to package.json to regenerate whenever models change:

{
  "scripts": {
    "zero:generate": "lucid-zero generate",
    "postinstall": "npm run zero:generate"
  }
}