Code Generators
Relevant source files
The following files were used as context for generating this wiki page:
Code generators in the Loco framework provide a productivity-first toolkit for rapidly building and deploying Rust-based applications. They allow developers to create various application components—such as models, controllers, migrations, and full CRUD scaffolds—using a predefined set of rules and templates. This system is designed to minimize boilerplate and enforce structural consistency across the project.
Sources: loco-gen/src/lib.rs:1-15, src/cli.rs:121-125, docs-site/config.toml:1-10
Architecture and Core Components
The generation system is built on top of the rrgen crate and utilizes the Tera template engine for rendering files. The logic is encapsulated within the loco-gen library, which defines the available components and handles the data mapping between CLI inputs and Rust code.
Execution Flow
The following diagram illustrates how a generation request moves from the CLI to the final file output:
The generator identifies whether to use local overrides or default embedded templates before rendering. Sources: loco-gen/src/lib.rs:271-300, src/cli.rs:693-718
Component Types
Loco supports several types of generators, categorized by the architectural layer they affect:
| Component | Description |
|---|---|
| Model | Generates data structures, SeaORM entities, and test logic. |
| Migration | Creates SQL migration files for database schema changes. |
| Controller | Generates web request handlers and routing logic. |
| Scaffold | A composite generator creating models, controllers, and views simultaneously. |
| Deployment | Generates infrastructure files like Dockerfiles and Nginx configs. |
| Task / Worker | Generates boilerplate for background processing and ad-hoc tasks. |
Sources: loco-gen/src/lib.rs:163-220, src/cli.rs:127-224
Scaffold and Controller Specializations
Scaffolding is one of the most powerful features, offering different "flavors" of implementation based on the application's frontend strategy.
Scaffold Kinds
Generators support three primary implementation styles:
- Api: Generates JSON-based endpoints for RESTful services.
- Html: Generates server-rendered templates using the Tera engine.
- Htmx: Generates views optimized for HTMX-powered dynamic interfaces.
Type Mapping and Schema Definition
The generator uses a mapping system (defined in mappings.json) to translate CLI field definitions into Rust types, database schemas, and SeaORM column types.
Key Data Structures
FieldType: Defines the name, rust type, schema, and column type for a field.RustType: Can be a simple string or a map (e.g., for specialized arrays).Mappings: A collection that resolves these types during the generation process.
Sources: loco-gen/src/lib.rs:60-125
Example Mapping Logic
When a user provides title:string, the generator looks up "string" in the mappings:
- Rust Type:
String - Schema Field:
string - Column Type:
String
Sources: loco-gen/src/lib.rs:90-110, loco-gen/src/lib.rs:430-445
Template Overrides and Customization
Developers can take control of the generation process by overriding default templates.
Local Template Management
- Command:
cargo loco generate override [PATH] - Location: Local templates are stored in
common/templates. - Precedence: If a file exists in the local template directory, the generator prioritizes it over the built-in default templates.
Sources: loco-gen/src/lib.rs:271-285, src/cli.rs:244-255
Deployment Generation
Deployment generators utilize the project's configuration to tailor output. For example, the Docker generator detects if a frontend folder exists to configure multi-stage builds or client-side rendering support.
Sources: src/cli.rs:343-365, loco-cli/README.md:65-80
Summary
Code generators in Loco serve as the primary interface for rapid development, abstracting the complexity of setting up SeaORM models and Axum controllers. By providing specialized scaffolds for API, HTML, and HTMX, and allowing for extensive template overrides, the system balances automated efficiency with developer flexibility.
Sources: DEVELOPMENT.md:30-35, docs-site/config.toml:145-155