Database-First TypeScript CRUD Generator

The Reepolee generator introspects your database schema and produces a complete, working CRUD module - route handlers, SQL queries, form and list templates, Zod validation, and translation keys in the database - in a single command. The output is real code you own and can edit freely; the generator is a starting point, not a runtime dependency.

bun reeman crud all

Editing the DDL by hand as your schema grows? Reepolee Studio is a visual editor for these SQL files, installed directly into your app, with live DDL preview and a domain-type palette drawn from your own project.

Via reeman

reeman (bun reeman) is the single entry point for the generator - an interactive grouped menu of generators, page scaffolds, database/config tasks, and maintenance actions with no flags to remember:

bun reeman

On a fresh database (no users table yet) it offers to run Quick Start first. After each action you press Enter and return to the menu; choose Exit to quit.

Every action is also reachable as a scripted subcommand - bun reeman <subcommand> [args] - covered in CLI Commands below. The interactive menu and the subcommands call the same underlying functions, so scripting a step never falls behind picking it from the menu.

CRUD Generators

Simple Pages

Database & Config

Tools & Maintenance

Route management lives here too, alongside the schema and translation maintenance tools:

The CRUD flows prompt interactively for options like prefix, parent, and index-grid columns where relevant. For scripted runs with --prefix, --parent, --pagination, or --grid-columns, use the CLI below.

CLI Commands

All generator commands go through bun reeman <subcommand>:

bun reeman schema <table> [--grid-columns <a,b,c>] # introspect one table and write schema files only
bun reeman schema all-tables                      # introspect every table
bun reeman crud <table> [--grid-columns <a,b,c>]  # full pipeline: schema + CRUD for one table
bun reeman crud all                               # full pipeline: schema + CRUD for every table (alias: all-tables)
bun reeman bulk <table...>                        # generate CRUD for a specific set of tables (always forces overwrite)
bun reeman refresh-crud <table> [--mode fields|full]  # regenerate CRUD for a route that already has a schema folder

For prefixed routes (e.g. /admin/...), bun reeman crud <table> --prefix admin is the invocation - see Prefixed Routes below.

schema and crud are intentionally separate steps so you can review the introspected types before committing to the generated UI - schema only introspects, crud runs the full pipeline (schema + CRUD generation) for one table or, with all/all-tables, for every table.

Run bun reeman --help (or bun reeman help) for the full command reference, including the route, database/config, locale, and translation subcommands (remove-route, set-db-type, upload-image, add-locale, sync-translations, check-domain-compliance, prune-translations, sync-missing-translations, and more). Every subcommand run this way is also appended to .reepolee/reeman.sh / .reepolee/reeman.ps1, so a scripted session can be replayed later.

Flags

What Gets Generated

Running the generator against a users table produces:

routes/users/
├── schema/
│   ├── table.generated.ts      # types, field metadata - regenerated on each run
│   ├── table.ts                # column definitions you can edit - written once
│   └── validation_server.ts   # Zod schemas - regenerated on each run
├── index.ts                    # route handlers
├── sql.ts                      # database query functions
├── index.ree                   # list template with search, sort, pagination
└── form.ree                    # create / edit template

routes/routes.ts is also updated automatically with the import and route entry for the new module.

Each generated field in form.ree also gets an empty hint slot - <p class="..."><!-- hints.<field> --></p> - a placeholder for optional per-field help text. It isn't populated automatically; write the hint copy in and wire it to a hints.<field> translation key by hand when a field needs one.

Schema Generation

The schema step connects to your database using CONNECTION_STRING from .env and introspects the table structure. It detects column types, nullability, foreign key relationships, and any field metadata embedded in column comments.

Each generator entry point takes one fresh, in-memory schema snapshot at startup and shares it through that run. There is no persisted DDL cache and no rescan command: the next schema, crud, bulk, or refresh-crud invocation automatically reads the database again. The long-running MCP generator tools also refresh the snapshot before generating, so apply your database change first and then run the generator normally.

Column comments drive field metadata. They come in two forms, and JSON takes precedence when both are present:

JSON comments - an object of extra hints:

ALTER TABLE products ADD COLUMN price DECIMAL(10,2) COMMENT '{"min": 0, "max": 99999}';
ALTER TABLE users    ADD COLUMN bio   TEXT          COMMENT '{"type": "textarea"}';

Plain-word comments - a bare keyword naming the field type (autocomplete, textarea, markdown, tags, …). This replaces the older field_overrides pattern where hints were generated commented-out in table.ts and uncommented by hand.

Column Visibility Flags (ICU / CU)

A plain-text comment may also carry a visibility flag controlling where the field appears:

The flag is matched as a standalone word, so CU only takes effect when ICU isn't also present. This keeps wide tables readable: only the most relevant columns show in the list, while every column remains editable. Set the flag in the column comment (MySQL only; SQLite has no column comments), or omit it to take the ICU default and pare the list down later with IGNORE_INDEX_FIELDS or the CU flag per column.

Generated columns (MySQL VIRTUAL/STORED, SQLite hidden columns) are detected during introspection. The required display column, and optional option_display, stay available as readable metadata but are omitted from generated create and update inputs. Other generated table columns are omitted from generated CRUD metadata.

Choosing Index Grid Columns

When you generate one table interactively through Single table or Schema only, Reeman shows a multi-select list of eligible index-grid columns. It labels the generator's usual first five usable columns as defaults, with image and file fields last. Use Space to toggle a column, Ctrl+A to select all, then Enter to confirm. A confirmed selection has no column-count limit.

The choice is written to the new route's schema/table.ts: every unselected eligible column receives grid: false. It stays in the schema and can still be used as a filter; it simply does not take horizontal space in the list grid. To make the same choice from automation, pass a comma-separated list:

bun reeman crud books --grid-columns title,author,isbn,published_on

For bulk and all-table generation there is no per-table prompt, so the five-column default applies. Existing table.ts files are never replaced for a grid selection: their widths, classes, comments, and existing grid settings remain owned by the project.

The generator maps database types to HTML input types and TypeScript types automatically:

Foreign Keys

Foreign key relationships are detected three ways: explicit FOREIGN KEY constraints, the {singular_table}_{column} naming convention, or a column name ending in _id whose target table+column exist. Either way, the generator renders that field as a dropdown populated from the related table - a plain <select>, or the searchable <auto-complete> component (components/auto-complete.ree) when the column is marked autocomplete, which gives live search, keyboard navigation, and autoscroll for large reference tables.

Every generated table and view must expose a string display column: its canonical, stable row label. The generator uses it for FK dropdowns and autocomplete lookups. If the table or view also exposes a string option_display, selectors use that richer label instead, while display remains the canonical value. For example, a company can use its name for display and name || ' - ' || vat_id for option_display.

When a v_<table> view joins an FK, it must expose the relationship label as <relationship>_display, such as developer_display for developer_id. The generated grid then hides the raw ID, shows the resolved label with the relationship name as its heading, and sorts that FK by its resolved label. The canonical display and option_display fields are readable and sortable but omitted from default grid columns.

CRUD Generation

The CRUD step reads the schema files and writes the route handlers, SQL functions, and templates. The following URL pattern is registered for each resource:

The list view supports URL-driven state - search query, sort field, sort direction, pagination position (offset, or cursor params), and per-page limit are all carried as query parameters, making every filtered view bookmarkable and shareable. The pagination row in index.ree renders four navigation controls - first, previous, next, last - driven by first_url, prev_url, next_url, and last_url returned from the handler. Each one renders as a disabled icon when there's nothing to navigate to, so the bar stays visually stable on the first and last page rather than reflowing when a button appears or disappears.

A few details the generator handles automatically:

• Two pagination strategies. Offset (the default) and cursor (keyset), selectable per-route - see Pagination below.
• Sort options from id, display, and indexed columns. The sort dropdown always includes the primary ID and canonical display label, then adds indexed columns (stored as indexed_columns in table.ts). FK IDs resolve to their <relationship>_display view column when available. Columns in IGNORE_ORDER_FIELDS are excluded.
• Fulltext search. When a table has a search_text column, search uses a fulltext query (MySQL MATCH … AGAINST, SQLite LIKE) instead of LIKE '%term%', via lib/sql_dialect.ts. Requires a MySQL FULLTEXT index.
• Cache + scope integration. Each generated sql.ts exports TABLE_NAME and VIEW_DEPENDENCIES, and list queries run through the optional SQL cache with the active global scope folded into the cache key.

Pagination

Generated list views support two pagination strategies, chosen at generation time with --pagination and recorded as a pagination_strategy export in schema/table.ts:

export const pagination_strategy: "cursor" | "offset" = "offset";

The generator branches on this value at codegen time - there is no runtime switch - producing the matching SQL, URL-param parsing, pagination-URL building, and template rendering. It defaults to "offset" when the export is absent (the same once-and-edit pattern as enable_delete).

Both render the same first/prev/next/last icon-button bar. Offset is the better default for admin grids where a stable, jump-to-page range display matters; choose cursor for large or fast-changing tables where deep-page performance matters more than positional display.

Streaming List Views (DPU)

Animation - streaming list: shell first, rows fill in

A generated list view can render synchronously (the default) or stream its records as Declarative Partial Updates (DPU), selectable per-route via the render_strategy export in schema/table.ts:

export const render_strategy: "stream" | "load" = "load";

• "load" (default) - runs the DB queries, then returns one fully-rendered Response.
• "stream" - renders the page shell (layout, nav, controls) immediately as the first chunk of a ReadableStream, then streams the pagination bar and record rows as <template for="…"> chunks once the DB queries resolve. The shell appears instantly even when the query is slow; the rows fill in when ready.

Like pagination, the generator branches on this value at codegen time (no runtime branching), selecting the streaming GET-handler template (offset or cursor variant) and wrapping the records/pagination regions in <?start name="…"> / <?end> DPU markers in index.ree.

Streaming relies on a small vendored polyfill (static/dpu.min.js, GoogleChromeLabs' HTML <template> setters polyfill, fetched by bun get:dpu). Its <script> tag in routes/layout.ree ships commented out - uncomment it when you deploy streaming to production.

Prefixed Routes

The --prefix flag scopes a resource under a sub-path. This is the standard way to build an admin panel:

bun reeman crud users --prefix admin

Files are written to routes/admin/users/ and routes/routes.ts is updated to mount them with mount_prefix:

...mount_prefix("/admin", admin_users_crud, require_module_mw("admin")),

The second argument to mount_prefix is an optional middleware guard. require_module_mw("admin") redirects any request from a user who doesn't have the admin module in their users.modules_tags field before the handler runs. You can swap it for require_auth_mw() or any custom middleware. Available modules are loaded from the modules table - see Authorization.

Nested Resources (Parent/Child)

The --parent <table> flag generates a resource as a child of another table - records scoped to a single parent and managed under nested URLs like /orders/:order_id/items:

bun reeman crud items --parent orders

The parent foreign key is auto-detected from the child table's FK constraints at introspection time and recorded as a parent export in schema/table.ts, which you can override:

export const parent = {
    table: "orders", // parent table
    fk_column: "order_id", // FK column in THIS table
    route_param: "order_id", // URL param name
};

What nesting produces:

• Child routes carry the parent segment: POST /orders/:order_id/items (create), GET /orders/:order_id/items/new, and GET|POST /orders/:order_id/items/:item_id/edit. There is no dedicated child index page and no bulk-delete - children are viewed on the parent's edit form.
• Scoped SQL. Every child query takes the parent id and filters WHERE parent_fk = ?; single-record lookups also verify the parent matches, so you can't reach a child scoped to a different parent.
• Parent integration. The generator edits the parent's files too: the parent sql.ts gains a get_<children>_by_<fk>() query, the parent index.ts edit handler loads the children, and the parent form.ree gets a managed crud:children marker section rendering an inline child list (all rows, no pagination/search/sort, with edit + delete actions).
• Return-URL flow. Child new/edit forms hide and pre-fill the parent FK and set _return_url back to the parent edit page, so create/update/delete redirects land on /orders/:order_id/edit.

Nesting is single-level (parent → child); a parent can have multiple children. The parent FK field in the child form renders as a hidden input inside a <field-wrapper> and is excluded from validation since it's set programmatically.

Excluding Tables with crud-ignore

Besides IGNORE_TABLES in config, you can exclude a table directly from the database by adding the tag crud-ignore to its table comment. Tagged tables drop out of reeman table listings, the bulk CRUD generator, and the crud all generation path - handy for internal/system tables and join tables you annotate in the schema rather than in code. The tag is case-insensitive. (MySQL only - SQLite has no table comments.)

Configuration

The generator respects several settings in config/db_structure.ts (full reference: Database Structure Config):

export const IGNORE_TABLES = ["modules", "sessions", "email", "images", "files", "users", "translations"] as const;

export const MAINTENANCE_FIELDS = ["created_at", "updated_at"] as const;

export const DATE_SUFIXES = ["_on", "_by"] as const;
export const DATETIME_SUFIXES = ["_at"] as const;

export const IGNORE_INDEX_FIELDS = [
    "display",
    "option_display",
    "option_text",
    "search_text",
    "hashed_password",
    "previous_hashed_password",
] as const;

export const IGNORE_ORDER_FIELDS = ["option_display", "search_text", "hashed_password", "previous_hashed_password"] as const;

export const BOOLEAN_PREFIXES = ["is_", "has_", "can_"] as const;

export const MIN_PASSWORD_LENGTH = Bun.argv.includes("--dev") ? 1 : 8;

IGNORE_TABLES - Tables the generator skips entirely. Add tables that don't need a UI here. The shipped list excludes framework tables (sessions, modules, images, files, users, translations) and the hand-written email admin. You can also exclude a table from the database side with the crud-ignore table comment.

MAINTENANCE_FIELDS - Fields managed by the database itself. Excluded from form schemas and from user-supplied write payloads; still readable on edit pages as read-only timestamps.

DATE_SUFIXES / DATETIME_SUFIXES - Column-name suffixes that signal date or datetime fields. A column ending in _on or _by (incorporated_on, payment_due_by) gets the date codec applied; a column ending in _at (created_at, verified_at) gets the datetime codec. The codecs handle conversion between database format and the format HTML date inputs expect.

IGNORE_INDEX_FIELDS - Fields hidden from the list table. display and option_display remain available to generated code but are not default columns; the resolved <relationship>_display fields in a view are the human-facing grid labels. The list also excludes sensitive values (hashed_password, previous_hashed_password) and internal search/option fields. For per-column control without a global list, use the CU visibility flag in the column comment instead.

IGNORE_ORDER_FIELDS - Columns excluded from the sort dropdown even when they're indexed. Mirrors IGNORE_INDEX_FIELDS but for ordering - keeps internal columns like search_text and password hashes out of the sort options.

BOOLEAN_PREFIXES - Column names starting with these prefixes are rendered as a Yes/No select instead of a checkbox. Useful when you want the value to be explicit ("Yes" or "No") rather than depending on whether a checkbox was checked.

MIN_PASSWORD_LENGTH - Minimum length enforced by the auth flows. Relaxed to 1 in development (--dev flag) so test accounts are easy to create; hardened to 8 in production.

Translations

The generator produces auto-generated labels for each field (e.g. created_at becomes "Created at"). It also syncs the resource's navigation label directly into the translations database table (namespace = the route's nav key, key_path = "nav"), so a freshly generated resource shows up in the sidebar without editing JSON. The database is the source of truth for translations - see Translations.

To fill in missing translations automatically, pass --translate:

bun reeman crud users --translate

This calls the configured AI provider (OpenRouter/Claude Haiku by default, or Ollama / Hugging Face - see Dynamic Translations) to translate every missing key.

To fill keys missing across locales after the fact, sync-translations scans the translations database table (not JSON), AI-translates any key present in one locale but missing in another, and writes the results back to the DB:

bun reeman sync-translations --translate

To find and fill keys referenced in templates but not yet in the database - or to prune DB keys no longer referenced by any template - use the Sync missing translations and Prune unused translations reeman tools. Both emit a reviewable .sql file rather than touching the DB directly. See Translations for the full DB-first workflow.

Editing Generated Files

Not all generated files are equal:

table.ts is the intended customisation point for the schema layer. Change column labels, swap an input type, adjust the grid layout, or add display-only computed fields - none of those changes will be lost when you re-run the generator.