Introduction to Loco
Relevant source files
The following files were used as context for generating this wiki page:
Loco is a productivity-first web and API framework for Rust, strongly inspired by Ruby on Rails. Described as the "one-person framework," it is designed to empower solo developers and small teams to build side projects and startups rapidly. By emphasizing "Convention Over Configuration," Loco reduces boilerplate code and provides a cohesive set of tools—including an ORM, background jobs, a scheduler, and a powerful CLI—to manage the entire application lifecycle from development to deployment.
The framework leverages established Rust libraries such as Axum for web routing, SeaORM for database interactions, and Tokio for asynchronous task execution. Its primary goal is to provide the expressive developer experience of Rails while maintaining the performance, safety, and stability inherent to the Rust ecosystem.
Sources: README.md:19-30, docs-site/content/_index.md:3-36, docs-site/content/blog/hello-world.md:26-38
Core Philosophy and Features
Loco is built on the principle of the "One Person Framework," prioritizing tools that save time and reduce decision fatigue for developers.
| Feature | Description | Key Components |
|---|---|---|
| Convention Over Configuration | Sensible defaults to minimize boilerplate and configuration time. | Sensible defaults, standard directory structures. |
| ORM Integration | Rich entities and active record patterns without writing manual SQL. | SeaORM |
| Controllers & Routing | Performance-oriented request handling and content-aware responses. | Axum |
| Background Jobs | Compute/IO intensive tasks handled via Redis or internal threads. | Tokio, Redis |
| CLI Tools | A comprehensive driving tool for code generation and project operation. | loco-cli, rrgen |
| Deployment | Simplified deployment stories including Docker and Nginx generation. | cargo loco generate deployment |
Sources: README.md:33-65, docs-site/config.toml:79-178, docs-site/content/blog/hello-world.md:65-85
System Architecture
Loco integrates several specialized Rust libraries into a unified framework. The following diagram illustrates how a user request flows through the Loco system components.
The diagram shows the standard request-response lifecycle where Axum handles routing and SeaORM manages data persistence, while background tasks are offloaded to workers.
Sources: README.md:33-65, docs-site/content/blog/hello-world.md:26-38, docs-site/config.toml:122-140
Application Components
Loco applications are structured around several key layers:
- Controllers: These handle incoming web request parameters and body validation. They use Axum for performance and support content-aware rendering (HTML, JSON, or text).
- Models: Based on SeaORM, models define the business logic, relationships, and validation for data entities.
- Views: Support for server-side templates (via Tera) or strongly typed JSON responses using Serde.
- Tasks & Scheduler: Ad-hoc scripts or scheduled jobs (crontab alternative) for maintenance and marketing logic.
Sources: docs-site/config.toml:79-158, docs-site/content/blog/hello-world.md:26-38
Development Workflow
Loco provides a CLI-driven workflow to accelerate development from project initialization to entity generation.
This sequence demonstrates the typical process of creating a new application, scaffolding an entity, and starting the development server.
Sources: README.md:76-104, snipdoc.yml:19-61, loco-cli/README.md:1-25
Key CLI Commands
The cargo loco command is the primary interface for managing a Loco project.
| Command | Purpose |
|---|---|
loco new | Generates a new Loco application from a starter template. |
cargo loco start | Starts the web server in the specified environment. |
cargo loco doctor | Validates local resources (DB, Redis, SeaORM CLI). |
cargo loco generate scaffold | Creates models, controllers, and migrations for a new entity. |
cargo loco db reset | Drops and fresh-migrates the database structure. |
cargo loco db entities | Generates SeaORM entities from the current DB schema. |
cargo loco task <name> | Executes a specific ad-hoc management task. |
Sources: snipdoc.yml:2-150, DEVELOPMENT.md:31-41, loco-cli/README.md:12-25
Project Maintainability
Loco includes built-in tools to ensure long-term stability and code quality.
- Loco Doctor: A diagnostic tool that checks for "blessed" dependencies (like
sea-orm-clioraxum) and validates database/Redis connectivity to prevent environment-related failures. - Testing Kit: Includes support for snapshot testing (via
insta) and CLI output verification (viatrycmd). It simplifies testing models, controllers, and background jobs with minimal effort. - Error Handling: Utilizes the
thiserrorcrate to provide informative, non-cryptic errors that help developers identify and fix issues quickly.
Sources: DEVELOPMENT.md:1-25, 77-105, docs-site/content/_index.md:32-36
Summary
Loco provides a cohesive environment for Rust developers to build full-stack applications with the speed typically associated with dynamic languages. By integrating Axum, SeaORM, and a powerful CLI, it handles the "heavy lifting" of web development—routing, persistence, background processing, and deployment—allowing developers to focus entirely on their business logic. Its "one-person framework" philosophy makes it an ideal choice for startups and independent hackers who require Rust's performance and safety without the overhead of manually wiring together disparate libraries.
Sources: docs-site/content/_index.md:3-36, docs-site/content/blog/hello-world.md:100-115