ZodRails

CI Gem Version Downloads License Ruby 3.2+ Rails 7.0+ Zod 4

Generate Zod schemas from ActiveRecord models
Bridge the gap between your Rails backend and TypeScript frontend with type-safe validation.

Generate Zod schemas from your ActiveRecord models. Bridge the gap between your Rails backend and TypeScript frontend with type-safe validation that stays in sync with your database schema and model validations.

Why ZodRails?

When building Rails APIs consumed by TypeScript frontends, you often duplicate validation logic: once in your Rails models, again in your frontend forms. ZodRails eliminates this duplication by generating Zod schemas directly from your ActiveRecord models, including:

  • Database column types mapped to Zod types
  • Rails validations (presence, length, numericality, format) mapped to Zod constraints
  • Enums generated as z.enum() with proper string literals
  • Nullable columns and default values handled correctly
  • Separate schemas for API responses vs. form inputs

Requirements

  • Ruby 3.2+
  • Rails 7.0+ (uses ActiveRecord and Railtie)
  • Zod 4.x in your frontend project

Installation

Add to your Gemfile:

gem "zod_rails"

Then run:

bundle install

Quick Start

1. Configure the gem

Create an initializer at config/initializers/zod_rails.rb:

ZodRails.configure do |config|
  config.output_dir = Rails.root.join("app/javascript/schemas").to_s
  config.models = %w[User Post Comment]
end

2. Generate schemas

bin/rails zod_rails:generate

3. Use in your frontend

import { UserSchema, UserInputSchema, type User } from "./schemas/user";

// Validate API response
const user = UserSchema.parse(apiResponse);

// Validate form input
const formData = UserInputSchema.parse(formValues);

Configuration Options

Option Default Description
output_dir app/javascript/schemas Directory for generated TypeScript files
models [] Array of model names to generate schemas for
schema_suffix Schema Suffix for response schemas (e.g., UserSchema)
input_schema_suffix InputSchema Suffix for input schemas (e.g., UserInputSchema)
generate_input_schemas true Whether to generate input schemas
excluded_columns ["id", "created_at", "updated_at"] Columns to exclude from input schemas
post_generate_command nil Shell command to run after a successful generation (e.g., your formatter)

Full Configuration Example

ZodRails.configure do |config|
  config.output_dir = Rails.root.join("frontend/src/schemas").to_s
  config.models = %w[User Post Comment Tag]
  config.schema_suffix = "Schema"
  config.input_schema_suffix = "FormSchema"
  config.generate_input_schemas = true
  config.excluded_columns = %w[id created_at updated_at deleted_at]
end

Type Mappings

Rails/DB Type Zod Type
string, text z.string()
integer z.int()
float z.number()
bigint z.string() (avoids JS Number overflow)
decimal z.string() (preserves BigDecimal precision)
boolean z.boolean()
date z.iso.date()
datetime, timestamp z.iso.datetime()
json, jsonb z.json()
uuid z.uuid()
time z.string()
binary z.string()
enum z.enum([...])

Validation Mappings

ZodRails introspects your model validations and maps them to Zod constraints:

Rails Validation Zod Constraint
presence: true .min(1) for string/text columns
length: { minimum: n } .min(n)
length: { maximum: n } .max(n)
length: { is: n } .length(n)
numericality: { greater_than: n } .gt(n)
numericality: { greater_than_or_equal_to: n } .gte(n)
numericality: { less_than: n } .lt(n)
numericality: { less_than_or_equal_to: n } .lte(n)
format: { with: /regex/ } .regex(/regex/) (preserves /i case-insensitivity)
inclusion: { in: n..m } (Range) .min(n).max(m)
inclusion: { in: %w[a b c] } (Array, string column) z.enum(["a", "b", "c"]) as the base type
inclusion: { in: [1, 5, 10] } (Array, integer column) .pipe(z.union([z.literal(1), z.literal(5), z.literal(10)]))

inclusion vs. Rails enum

The Rails enum macro and a string column with validates :foo, inclusion: { in: %w[...] } both end up as z.enum([...]) in the generated TypeScript:

  • enum :role, { member: 0, admin: 1 } introspects through ActiveRecord's defined_enums and emits z.enum(["member", "admin"]).
  • validates :decision, inclusion: { in: %w[pending approved] } on a string column is detected by SchemaBuilder and produces z.enum(["pending", "approved"]) as the base type. presence: true becomes redundant once the values are restricted, so it's dropped from the chain.

If you mix both (enum macro AND a separate inclusion validator on the same column), the enum macro wins.

Generated Output Example

Given this Rails model:

class User < ApplicationRecord
  enum :role, { member: 0, admin: 1, moderator: 2 }

  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
  validates :name, presence: true, length: { minimum: 2, maximum: 100 }
  validates :age, numericality: { greater_than: 0, less_than: 150 }, allow_nil: true
  validates :status, inclusion: { in: %w[pending active suspended] }
end

ZodRails generates:

import { z } from "zod";

export const UserSchema = z.object({
  id: z.int(),
  email: z.string().min(1).regex(/^[^@\s]+@[^@\s]+$/),
  name: z.string().min(2).max(100),
  age: z.int().gt(0).lt(150).nullable(),
  status: z.enum(["pending", "active", "suspended"]),
  role: z.enum(["member", "admin", "moderator"]),
  created_at: z.iso.datetime(),
  updated_at: z.iso.datetime()
});

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

export const UserInputSchema = z.object({
  email: z.string().min(1).regex(/^[^@\s]+@[^@\s]+$/),
  name: z.string().min(2).max(100),
  age: z.int().gt(0).lt(150).nullish(),
  status: z.enum(["pending", "active", "suspended"]),
  role: z.enum(["member", "admin", "moderator"]).optional()
});

export type UserInput = z.infer<typeof UserInputSchema>;

Schema vs InputSchema

ZodRails generates two schema variants:

Schema (e.g., UserSchema)

  • Represents data as returned from your API
  • Includes all columns (id, timestamps, etc.)
  • Uses .nullable() for nullable columns

InputSchema (e.g., UserInputSchema)

  • Represents data for form submission
  • Excludes configured columns (defaults: id, created_at, updated_at)
  • Uses .optional() for columns with database defaults
  • Uses .nullish() for nullable columns (accepts both null and undefined)

Preserving Hand-Written Code

The generator overwrites files in output_dir on every run. If you want to keep hand-written schemas, types, or imports next to the generated ones, wrap them in sentinel comments — the writer will preserve anything between the markers verbatim across regens.

Two block markers are recognized per file:

import { z } from "zod";

// ZOD_RAILS:CUSTOM:IMPORTS:BEGIN
import { customValidator } from "./shared";
// ZOD_RAILS:CUSTOM:IMPORTS:END

export const ArticleSchema = z.object({ /* generated */ });

export type Article = z.infer<typeof ArticleSchema>;

// ZOD_RAILS:CUSTOM:BEGIN
export const ArticleResponseSchema = z.object({
  article: ArticleSchema,
  meta: z.object({ count: z.int() }),
});
// ZOD_RAILS:CUSTOM:END
  • Imports block lives right after the import { z } from "zod"; line. Use it for any external imports your custom code needs.
  • Tail block lives at the end of the file. Use it for additional schemas, response wrappers, helper types, etc.

Both blocks are optional. If you don't add them, the file is overwritten as before. Hand-edits outside the markers will still be lost on regen — wrap them, or move them to a separate file.

Drift Detection in CI

bin/rails zod_rails:check regenerates schemas in memory and compares them against the files on disk. Exits 0 if everything is up to date, 1 with a list of out-of-date files otherwise. Wire it into your CI to catch the case where someone updated a model but forgot to regenerate:

- name: Check Zod schemas are up to date
  run: bin/rails zod_rails:check

For local iteration, DRY_RUN=1 bin/rails zod_rails:generate prints the same drift list without writing anything.

Formatter Integration

If your TypeScript project runs prettier, biome, or a similar formatter with conventions that differ from the gem's output (single quotes, trailing commas, line width…), set post_generate_command and the gem will hand off to your formatter after a successful generation:

ZodRails.configure do |config|
  config.post_generate_command =
    "bun run prettier --write 'app/javascript/schemas/**/*.ts'"
end

The command runs with your project's working directory. A nonzero exit raises ZodRails::Error so CI catches misconfiguration, and the generated files are still written before the formatter runs.

Integrating with Forms

ZodRails pairs well with form libraries that support Zod:

React Hook Form

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { UserInputSchema, type UserInput } from "./schemas/user";

function UserForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<UserInput>({
    resolver: zodResolver(UserInputSchema)
  });

  const onSubmit = (data: UserInput) => {
    // data is fully typed and validated
  };

  return <form onSubmit={handleSubmit(onSubmit)}>...</form>;
}

Validating API Responses

import { UserSchema, type User } from "./schemas/user";

async function fetchUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return UserSchema.parse(data); // Throws if invalid
}

CI/CD Integration

Use zod_rails:check to catch missed regenerations:

# .github/workflows/ci.yml
- name: Check Zod schemas are up to date
  run: bin/rails zod_rails:check

This works whether or not the generated schemas are committed to the same repo. If they are committed, the older git diff --exit-code approach also works:

- name: Generate Zod schemas
  run: bin/rails zod_rails:generate

- name: Check for uncommitted schema changes
  run: git diff --exit-code app/javascript/schemas/

Troubleshooting

Schemas not updating after model changes

Re-run the generator after any model changes:

bin/rails zod_rails:generate

Validation constraints not appearing

Ensure validations are defined on the model class, not in concerns that might not be loaded. Conditional validations (:if, :unless) are detected and excluded by default.

Custom column types

For custom types not in the mapping table, ZodRails falls back to z.unknown(). Open an issue if you need support for additional types.

Misconfigured model names

A typo in config.models no longer raises an uninitialized constant backtrace. The generator collects every unresolvable name and prints them all in one report:

ZodRails: 2 model(s) in config.models could not be loaded:
  - Useer
  - Postt

Check the model names in config/initializers/zod_rails.rb.

Namespaced models

A model like Admin::User writes to admin/user.ts and exports AdminUserSchema / AdminUser (the namespace separator is collapsed for the TypeScript identifier — :: is not valid in a TS identifier).

Releasing

  1. Bump the version in lib/zod_rails/version.rb
  2. Commit: git commit -am 'Bump version to x.y.z'
  3. Tag: git tag v<x.y.z>
  4. Push with tags: git push origin trunk --tags

The v* tag push triggers the release workflow, which runs CI and publishes to RubyGems via Trusted Publishing.

Development

After checking out the repo:

bundle install
bundle exec rspec

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b feature/my-feature)
  3. Commit your changes (git commit -am 'Add my feature')
  4. Push to the branch (git push origin feature/my-feature)
  5. Create a Pull Request

License

MIT License. See LICENSE for details.