Romance

Full-stack code generator for Rust + React. One command creates a complete project. Another generates full CRUD entities across the entire stack.

Think Django's startproject + startapp, but for Axum + SeaORM backends and React + TypeScript + shadcn/ui frontends.

romance new my-app
cd my-app
romance generate entity Post title:string body:text published:bool author_id:uuid->User
romance dev

That's it. You now have a working full-stack CRUD app with a Rust API, database migrations, TypeScript types, React forms, and auto-wired routes.

Features

Project Scaffolding

• Complete Axum + SeaORM backend with config, error handling, pagination, and CORS
• React 19 + TypeScript frontend with Vite, TanStack Query, and shadcn/ui
• PostgreSQL migrations via SeaORM, ready to run

Entity Generation

• Full CRUD across the entire stack from a single command
• Backend: SeaORM model, Axum handlers (list/get/create/update/delete), routes, migration
• Frontend: TypeScript types, API client, TanStack Query hooks, List/Form/Detail components
• 14 field types with automatic mapping across Rust, TypeScript, PostgreSQL, and UI components
• Inline validation rules and searchable field annotations

Relations

• BelongsTo with automatic reverse has-many injection into the target entity
• ManyToMany with auto-generated junction tables, handlers, and routes on both sides
• Deferred relations: M2M targets that don't exist yet are stored and applied when generated later

Authentication & Admin

• JWT auth generation: user entity, login/register handlers, frontend auth context and protected routes
• Admin panel generation: dashboard, layout, entity management for all existing entities

15 Addons

• Validation, soft-delete, audit logging, file/image storage, full-text search, OAuth, security headers, rate limiting, observability, email, i18n, caching, background tasks, WebSockets, API keys

Developer Experience

• romance dev runs backend + frontend concurrently
• romance check runs cargo check, cargo test, and tsc in one command
• romance test with automatic temporary database creation
• romance doctor to verify project health and dependencies
• romance destroy entity to cleanly remove generated code
• Shell completions for bash, zsh, fish, and PowerShell
• Idempotent code generation with custom code preservation via marker system

Quick Start

Install

cargo install romance-cli

Create a Project

romance new my-app
cd my-app

This generates:

my-app/
  backend/
    src/
      main.rs          # Axum server with CORS, config, error handling
      config.rs        # Environment-aware configuration
      db.rs            # SeaORM database connection pool
      errors.rs        # Unified error responses
      pagination.rs    # Cursor/offset pagination
      entities/mod.rs  # Entity models
      handlers/mod.rs  # Request handlers
      routes/mod.rs    # Route registration
    migration/
      src/lib.rs       # Migration runner
    Cargo.toml
    .env
  frontend/
    src/
      App.tsx          # React Router setup
      main.tsx         # Entry point with QueryClientProvider
      lib/utils.ts     # Tailwind merge utility
    package.json       # React 19, TanStack Query, shadcn/ui, Vite
    vite.config.ts
    tsconfig.json
  romance.toml         # Project configuration

Generate an Entity

romance generate entity Product title:string price:decimal description:text? in_stock:bool

This generates across the full stack:

Plus automatic registration in route files and App.tsx.

Add Relations

romance generate entity Category name:string
romance generate entity Product title:string category_id:uuid->Category tags:m2m->Tag
romance generate entity Tag name:string

The ->Category foreign key automatically injects a has-many reverse relation into Category. The m2m->Tag creates a junction table with handlers and routes on both sides.

Run the Dev Servers

romance dev

Starts cargo watch (backend) and npm run dev (frontend) concurrently.

Generated Stack

CLI Commands

Core Commands

Code Generation

Addons

Database

Maintenance

Field Types

Romance supports 14 field types. Each type is automatically mapped across every layer of the stack.

Field Modifiers

# Optional (nullable) field -- append ?
description:text?

# Foreign key -- append ->EntityName
category_id:uuid->Category

# Validation rules -- use brackets
title:string[min=3,max=100]
email:string[email]
slug:string[unique]
website:string[url]
code:string[regex=^[A-Z]{3}$]

# Searchable field (for full-text search addon)
title:string[searchable]
body:text[searchable]

# Combine modifiers
author_id:uuid[required]->User
title:string[min=3,max=200,searchable]

Relations

BelongsTo (Foreign Key)

romance generate entity Post title:string author_id:uuid->User

Creates a author_id UUID column on the posts table with a foreign key to users. If the User entity already exists, a has-many reverse relation is automatically injected into User's handlers and routes.

ManyToMany

romance generate entity Post title:string tags:m2m->Tag

Creates a post_tag junction table (alphabetical naming convention) with a model and migration. Injects list/add/remove handlers and routes into both Post and Tag. If Tag doesn't exist yet, the relation is stored in .romance/pending_relations.json and applied automatically when Tag is generated.

HasMany (Explicit)

romance generate entity User name:string posts:has_many->Post

Usually unnecessary since BelongsTo automatically injects the reverse. Use only when you need to explicitly declare the reverse side.

Addons

Addons extend your project with production-ready features via romance add.

Configuration

Romance projects are configured via romance.toml at the project root.

[project]
name = "my-app"
description = "My full-stack application"

[backend]
port = 3000
database_url = "postgres://localhost/my_app"
api_prefix = "/api"                          # Optional, for API versioning

[frontend]
port = 5173
api_base_url = "http://localhost:3000"

[codegen]
generate_openapi = true
generate_ts_types = true

[features]
validation = true
soft_delete = false
audit_log = false
search = true

[security]
rate_limit_rpm = 60
cors_origins = ["http://localhost:5173"]
csrf = false

[storage]
backend = "local"          # "local" or "s3"
upload_dir = "./uploads"
max_file_size = "10MB"

[environment]
active = "development"     # or set ROMANCE_ENV env var

Environment Overrides

Create romance.{env}.toml files for environment-specific settings:

# romance.production.toml
[backend]
port = 8080

The override file is deep-merged on top of the base config. Set the active environment via the ROMANCE_ENV environment variable or the [environment] active field.

How It Works

Romance uses a template-based code generation architecture:

1. CLI parses commands and field definitions into an EntityDefinition
2. Template Engine (Tera) builds context with type mappings for every target language
3. Templates (compiled into the binary via rust-embed) render to source files
4. Marker System (// === ROMANCE:TYPE === comments) enables incremental code insertion without overwriting user code
5. Custom Blocks (// === ROMANCE:CUSTOM ===) preserve hand-written code below the marker across re-generations
6. Manifest Tracking (.romance/manifest.json) stores SHA-256 hashes of generated files for the romance update command

The generator is fully idempotent: running the same command twice produces the same result without duplicating code.

Documentation

Detailed guides are available in the docs/ directory:

• Architecture -- crate structure, data flow, design decisions
• Templates -- template context variables, Tera filters, creating new templates
• Relations -- deep dive into BelongsTo, HasMany, ManyToMany internals
• Addons -- how addons work, creating custom addons
• Contributing -- development setup, checklists for new features

License

MIT License. See LICENSE for details. Both the CLI tool and all generated code output are free to use for personal and commercial projects.