# Loco

> The Loco documentation — tutorials, how-to guides, reference, and explanations for the one-person Rust framework.

- [Documentation](https://loco.rs/docs/): The Loco documentation — tutorials, how-to guides, reference, and explanations for the one-person Rust framework.

## Tutorials
- [Tutorials](https://loco.rs/docs/tutorials/): Learning-oriented lessons that take you from zero to a working Loco app.
- [Your First App](https://loco.rs/docs/tutorials/your-first-app/): Install Loco, generate a new app, scaffold a CRUD resource, and hit your first endpoint — a guaranteed-success first run.
- [The Tour](https://loco.rs/docs/tutorials/the-tour/): A faster, end-to-end walkthrough: a model with a relation, a hand-wired controller route, a background worker, and a task — in one sitting.
- [Build a Small Authenticated App](https://loco.rs/docs/tutorials/saas-with-auth/): Generate an app from the SaaS starter path, register and log in a user, call a JWT-protected endpoint, then protect one of your own.

## How-to guides
- [Add a model](https://loco.rs/docs/how-to/add-model/): Generate a model with a migration, add fields to it, and run the migration to get working entities.
- [How-to Guides](https://loco.rs/docs/how-to/): Problem-oriented recipes for getting a specific job done in Loco.
- [Query data with the condition DSL](https://loco.rs/docs/how-to/query-data/): Filter entities with ConditionBuilder operators, build date ranges, and sort results — without hand-writing Sea-ORM conditions.
- [Paginate query results](https://loco.rs/docs/how-to/paginate/): Page over entities with paginate/fetch_page, accept page/page_size from a request with PaginationQuery, and return a PageResponse from a controller.
- [Seed data](https://loco.rs/docs/how-to/seed-data/): Load fixture data into a fresh database, wire it into Hooks::seed, and dump/import table contents with cargo loco db seed.
- [Connect a second database](https://loco.rs/docs/how-to/multi-database/): Attach an extra database connection, or several, using the built-in multi_db initializer.
- [Add a database to an existing app](https://loco.rs/docs/how-to/add-a-database/): Turn an app generated with --db none into a database app: enable with-db, create the migration crate, and wire Hooks, the binaries, and config.
- [Add a controller](https://loco.rs/docs/how-to/add-controller/): Generate a controller, wire up its routes and handlers, and mount it under a prefix or nested path.
- [Validate requests](https://loco.rs/docs/how-to/validate-requests/): Validate JSON, form, and query-string payloads with Loco's validating extractors, and return structured or simplified errors.
- [Render server-side views](https://loco.rs/docs/how-to/render-views/): Render HTML with Loco's Tera-based ViewRenderer: create a template, wire the ViewEngine extractor, and use the format::render() builder.
- [Respond with different formats](https://loco.rs/docs/how-to/respond-formats/): Use the format:: response helpers (json, text, html, yaml, redirect, empty) and negotiate content type with RespondTo/Format.
- [Handle errors](https://loco.rs/docs/how-to/handle-errors/): Return unauthorized/bad_request/not_found from a handler, build a CustomError with an arbitrary status, and know what status code the framework sends for everything else.
- [Add middleware](https://loco.rs/docs/how-to/add-middleware/): Enable a built-in middleware through YAML config, and write a custom MiddlewareLayer when the built-ins don't cover what you need.
- [Serve static & SPA assets](https://loco.rs/docs/how-to/serve-assets/): Serve a static folder (or a single-page app) with the built-in static middleware, then optionally embed everything into the binary with the embedded_assets feature.
- [Add websockets / realtime](https://loco.rs/docs/how-to/websockets/): Loco has no built-in websocket layer — wire up realtime with an external Axum-compatible crate like socketioxide.
- [Build a typed React SPA](https://loco.rs/docs/how-to/build-a-spa/): Use Loco's clientside mode: a Vite + React + TanStack Query frontend whose TypeScript types are generated from your Rust DTOs by ts-rs, so a schema change breaks the frontend build instead of production.
- [Add a background worker](https://loco.rs/docs/how-to/add-worker/): Generate a worker, implement BackgroundWorker, enqueue a job with perform_later, and register it in connect_workers.
- [Choose a queue backend](https://loco.rs/docs/how-to/choose-queue-backend/): Pick Redis, Postgres, or SQLite for background jobs, configure it, and pick a worker mode.
- [Schedule recurring jobs](https://loco.rs/docs/how-to/schedule-jobs/): Configure the scheduler to run a task or shell command on a cron or English-language schedule.
- [Connect to Postgres and Redis over TLS](https://loco.rs/docs/how-to/connect-over-tls/): Reach managed Postgres (RDS, Supabase, Neon) and managed Redis (ElastiCache, Upstash) over encrypted TLS connections.
- [Write a one-off task](https://loco.rs/docs/how-to/write-task/): Implement the Task trait, register it, and run it with cargo loco task.
- [Send an email](https://loco.rs/docs/how-to/send-email/): Generate a mailer, write templates, and configure SMTP with the right TLS mode.
- [Configure file storage](https://loco.rs/docs/how-to/configure-storage/): Wire up the Storage API over local disk, in-memory, or cloud (S3/Azure/GCS) drivers, pick a mirror/backup strategy, and stream large files.
- [Use the cache](https://loco.rs/docs/how-to/use-cache/): Configure a cache driver (null/in-memory/Redis) and use get/insert/get_or_insert with expiry, ping, and clear.
- [Deploy to production](https://loco.rs/docs/how-to/deploy/): Build a release binary, generate a Dockerfile or nginx config with cargo loco generate deployment, and review production config before shipping.
- [Configure logging](https://loco.rs/docs/how-to/configure-logging/): Set logger level and format, understand the filtering precedence, and add a rotating file appender.
- [Load static data](https://loco.rs/docs/how-to/load-data/): Load read-only JSON data (hyperparameters, banlists, calendars) once per process using loco_rs::data, without a database round trip.
- [Protect a Route with JWT](https://loco.rs/docs/how-to/jwt-auth/): Add JWT authentication to a route with the JWT and JWTWithUser<T> extractors, implement the Authenticable contract, and generate tokens.
- [Protect a Route with an API Key](https://loco.rs/docs/how-to/api-key-auth/): Authenticate requests with a per-user API key using the ApiToken<T> extractor and Authenticable::find_by_api_key.
- [Configure Where Loco Looks for the JWT](https://loco.rs/docs/how-to/jwt-locations/): Set the JWT token location — Bearer header, query parameter, or cookie — as a single location or a fallback list.
- [Hash and Verify Passwords](https://loco.rs/docs/how-to/hash-passwords/): Use loco_rs::hash to Argon2id-hash passwords, verify them on login, and generate random tokens for reset links or API keys.
- [Write request (controller) tests](https://loco.rs/docs/how-to/request-tests/): Boot a test instance of your app and drive its HTTP routes with request/boot_test, RequestConfigBuilder, and axum-test assertions.
- [Write DB model tests](https://loco.rs/docs/how-to/model-tests/): Boot a database-backed test app with boot_test, seed fixtures, and get automatic per-test DB cleanup via BootResultWrapper's Drop.
- [Snapshot tests with fixtures and redactions](https://loco.rs/docs/how-to/fixtures-snapshots/): Use insta snapshots for models and responses, redact dynamic fields with cleanup_user_model/cleanup_email, and assert on rendered HTML with select().
- [Generate code with cargo loco generate](https://loco.rs/docs/how-to/use-generators/): Scaffold models, migrations, controllers, workers, and more with `cargo loco generate <kind>`, using the shared field:type mini-language.
- [Override a built-in generator template](https://loco.rs/docs/how-to/override-templates/): Use `cargo loco generate override` to copy a built-in .t template into your app so you can customize what generators produce.
- [Diagnose your app with cargo loco doctor](https://loco.rs/docs/how-to/run-doctor/): Run `cargo loco doctor` to validate DB/queue connectivity, dependency versions, and initializer health, and see how the environment changes which checks run.

## Reference
- [Configuration](https://loco.rs/docs/reference/configuration/): Exhaustive reference for every YAML key in a Loco app's config file: loading precedence, environment resolution, and every sub-config struct.
- [CLI reference](https://loco.rs/docs/reference/cli/): Every flag and subcommand for the `loco` app generator and the `cargo loco` runtime CLI.
- [Reference](https://loco.rs/docs/reference/): Information-oriented technical descriptions of Loco's machinery — configuration, CLI, generators, and APIs.
- [Generators & field types](https://loco.rs/docs/reference/generators/): Every `cargo loco generate <kind>` component, its exact CLI syntax and output files, plus the complete field-type mini-language used by model/migration/scaffold generators.
- [Feature flags](https://loco.rs/docs/reference/feature-flags/): The complete loco-rs Cargo feature matrix: defaults, what each flag enables, and how flags interact.
- [Middleware catalog](https://loco.rs/docs/reference/middleware/): Every built-in middleware: config key, struct, default state, and knobs.
- [AppContext & prelude](https://loco.rs/docs/reference/app-context/): The AppContext struct field-by-field, and everything use loco_rs::prelude::* brings into scope.
- [Hooks trait](https://loco.rs/docs/reference/hooks/): The complete Hooks trait surface: every required and provided method, its signature, and when it runs.
- [Error model](https://loco.rs/docs/reference/errors/): The loco-rs Error enum, its HTTP status mapping, the ErrorDetail JSON body, and the wrap/msg/string/bt constructors.
- [Schema & ColType DSL](https://loco.rs/docs/reference/schema-dsl/): The full migration schema DSL: the ColType column-type enum, table-level operations, references/enums, and the i64 auto-PK default.
- [Query DSL & pagination](https://loco.rs/docs/reference/query-pagination/): The ConditionBuilder fluent filter DSL, date-range helper, pagination API, and the model-layer error/Authenticable types.

## Explanation
- [Why "batteries included"?](https://loco.rs/docs/explanation/why-batteries-included/): The prime directive behind Loco's design: prefer a built-in or a generator over hand-wiring, and what that buys you.
- [Architecture: the request lifecycle](https://loco.rs/docs/explanation/architecture/): How a Loco app boots, how AppContext gets built, and how a request travels through routes, middleware, and back out — and why the middleware order is LIFO.
- [AppContext and dependency injection](https://loco.rs/docs/explanation/appcontext-and-di/): Why AppContext is the one piece of shared state every handler sees, and how SharedStore lets you extend it without forking the framework.
- [Explanation](https://loco.rs/docs/explanation/): Understanding-oriented discussion of how Loco works and why it is designed the way it is.
- [The configuration model](https://loco.rs/docs/explanation/configuration-model/): How Loco resolves an environment, which config file wins, why YAML is rendered through a template pass first, and how secrets flow in without a dedicated vault type.
- [The background-processing model](https://loco.rs/docs/explanation/background-processing-model/): Why perform_later works unmodified against Redis, Postgres, or SQLite, how the shared Driver trait keeps the two SQL backends in lockstep, and what priority and worker modes buy you.
- [Views and assets](https://loco.rs/docs/explanation/views-and-assets/): SSR with Tera vs. serving a SPA vs. embedding everything into the binary — and how one feature flag coordinates a swap across two subsystems at once.
- [Coming from Axum](https://loco.rs/docs/explanation/coming-from-axum/): Loco is Axum 0.8 with pre-wired decisions on top, not a replacement for it — how extractors, State, and the Router map across, and what Loco actually adds.

## Extras
- [Upgrades](https://loco.rs/docs/extras/upgrades/)
- [Extras](https://loco.rs/docs/extras/)

## Resources
- [Around the Web](https://loco.rs/docs/resources/around-the-web/)
- [FAQ](https://loco.rs/docs/resources/faq/): Answers to frequently asked questions.
- [Resources](https://loco.rs/docs/resources/)