Application Lifecycle & Hooks

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli.rs
• README.md
• docs-site/content/blog/frontend-website.md
• DEVELOPMENT.md
• docs-site/content/blog/hello-world.md
• loco-new/tests/templates/asset.rs

Loco is a productivity-first Rust web framework inspired by Ruby on Rails, designed to streamline the "one-person framework" experience. It manages the full application lifecycle from environment-aware configuration and database initialization to starting servers, background workers, and schedulers. The framework provides a structured approach to building applications by centralizing logic within specialized components and lifecycle hooks.

Sources: README.md, docs-site/content/blog/hello-world.md

Core Application Components

The Loco architecture is built around several key components that handle different aspects of the application's runtime. These include controllers for web requests, models for database interaction, and background infrastructure for asynchronous processing.

AppContext and Hooks

The AppContext serves as the central state of the application, carrying configuration, database connections, and queue providers. The Hooks trait allows developers to customize the application behavior at specific lifecycle points, such as loading configuration or initializing loggers.

The diagram shows the initialization flow from CLI execution to the application boot process.
Sources: src/cli.rs:596-615, src/cli.rs:72-87

Key Lifecycle Structures

Component	Description	Derived Source
AppContext	Contains shared state including database connections (db), configuration, and queue providers.	src/cli.rs:596-601
Hooks	A trait providing methods to hook into the app lifecycle (e.g., load_config, init_logger, app_version).	src/cli.rs:608-620
Environment	Encapsulates the runtime environment (e.g., development, test, production).	src/cli.rs:77
StartMode	Defines how the application starts: as a server, worker, or combined process.	src/cli.rs:72-87

Request & Route Lifecycle

Loco uses Axum for request handling. Routes are typically defined within controllers and registered in the main application file. The framework supports prefixes and versioning to organize API endpoints.

The sequence diagram illustrates the flow of a web request through the Loco stack.
Sources: docs-site/content/blog/hello-world.md, docs-site/content/blog/frontend-website.md

Route Configuration

Routes are added to the application via the routes hook. This allows for global prefixes, such as /api, and the inclusion of controller-specific routes.

// Example of route registration and prefixing
fn routes() -> AppRoutes {
    AppRoutes::with_default_routes()
        .prefix("/api")
        .add_route(controllers::notes::routes())
}

Sources: docs-site/content/blog/frontend-website.md

Background & Task Lifecycle

Loco provides integrated support for background jobs and one-off tasks. Jobs are typically backed by Redis or in-process threads, while tasks are linear business workflows accessible via the CLI.

Job Execution Flow

1. Definition: Implementing the Worker trait for a specific job.
2. Enqueuing: Calling perform_later from within a controller or model.
3. Processing: The worker process pulls jobs from the queue and executes the perform method.

CLI Task Interaction

Tasks are operational scripts that have full access to the AppContext. They are invoked using the cargo loco task <TASK_NAME> command.

Flow of executing an ad-hoc operational task.
Sources: src/cli.rs:673-677, docs-site/content/blog/hello-world.md

Deployment & Asset Lifecycle

The application supports different asset serving strategies, which are configured in the environment settings and affect how the server behaves during startup.

Asset Options

• None: No static assets served.
• Serverside: Serves static files from a local directory (e.g., assets/static).
• Clientside: Optimized for SPA frameworks (like React/Vite), serving a dist folder and providing a fallback to index.html.

Sources: loco-new/tests/templates/asset.rs:22-77

Deployment Lifecycle

Loco provides generators to create deployment artifacts like Dockerfile and Nginx configurations. During a Docker build, the framework detects static assets and includes them in the final image.

Step	Action	Command
1	Generate Deployment	cargo loco generate deployment
2	Build Assets	npm run build (if clientside)
3	Build Image	docker build -t app-name .
4	Run	docker run -e LOCO_ENV=production ...

Sources: docs-site/content/blog/frontend-website.md, src/cli.rs:528-560

Summary

The Loco application lifecycle is designed around a unified CLI and a set of developer-defined hooks. By centralizing environment resolution, configuration loading, and context creation, Loco ensures that whether the application is running as a web server, a background worker, or a one-off task, it maintains a consistent state and access to core resources like database connections and mailing infrastructure. This "one-person framework" philosophy prioritizes developer locality and operational simplicity, allowing a single binary to manage the entire application stack.