Storage System
Relevant source files
The following files were used as context for generating this wiki page:
The Storage System in Loco provides a unified interface for handling file operations across various environments. It facilitates working with files through multiple operations and supports diverse backends, including in-memory storage, local disk storage, and cloud services such as AWS S3, Google Cloud Platform (GCP), and Azure.
Sources: README.md:65-67
Loco integrates storage management directly into its framework architecture, allowing developers to configure how assets and data are persisted and served. This includes specialized support for static asset serving, template embedding, and deployment-ready configurations for production environments.
Sources: README.md:65-67, docs-site/content/blog/frontend-website.md:73-82
Architecture and Drivers
The storage system is designed to be pluggable, allowing the framework to switch between different storage strategies based on the application environment (development, testing, or production).
Storage Strategies
Loco supports several primary storage and asset handling strategies:
- Local Disk: Files are stored and served from the local filesystem, typically used during development.
- Cloud Storage: Integration with AWS S3, GCP, and Azure for scalable production storage.
- Embedded Assets: Files can be embedded directly into the Rust binary for simplified deployment.
Sources: README.md:65-67, tests/build_scripts/embedded_assets.rs:160-178
Asset Serving Configurations
During application generation via the CLI, users can select specific asset serving configurations that dictate how the storage system interacts with the frontend.
| Configuration | Description |
|---|---|
Serverside | Standard server-side rendering where assets are served from a designated static folder. |
Clientside | Optimized for Single Page Applications (SPAs) like React or Angular, where the storage system handles frontend build artifacts. |
None | Disables framework-level static asset handling. |
Sources: loco-new/tests/templates/asset.rs:20-66
Static Asset Management
Loco provides built-in middleware to serve static files directly from the server. This is configured within the application's environment-specific YAML files.
Configuration Structure
Static serving is defined under the server.middlewares.static section of the configuration. Key parameters include the URI mapping, the physical file path, and fallback mechanisms for client-side routing.
The diagram above illustrates the configuration schema for the static asset middleware.
Sources: docs-site/content/blog/frontend-website.md:73-82, loco-new/tests/templates/asset.rs:48-61
Middleware Behavior
When Clientside serving is enabled, the storage system typically disables the default framework fallback to prioritize static file resolution. This ensures that a Vite or Angular build folder (e.g., frontend/dist) is correctly reached by the web server.
Sources: docs-site/content/blog/frontend-website.md:88-96, loco-new/tests/templates/asset.rs:52-54
Embedded Assets System
For single-binary deployments, Loco includes a system to embed assets directly into the application. This system scans directories and generates Rust code that represents the file contents.
Build Integration
The framework uses a build script logic to discover directories, collect files, and generate asset mappings. This process transforms physical files into static_assets.rs and view_templates.rs files during the compilation phase.
The sequence shows how assets are discovered and converted into embedded Rust code during build.
Sources: tests/build_scripts/embedded_assets.rs:8-18, tests/build_scripts/embedded_assets.rs:160-178
Key Embedding Functions
collect_all_files: Traverses directories to map filesystem paths to unique asset keys.generate_asset_code: Produces the Rust source code that allows the application to access files as in-memory bytes.find_app_directory: Locates the project root by searching forCargo.tomlto ensure correct path resolution during build.
Sources: tests/build_scripts/embedded_assets.rs:136-158, tests/build_scripts/embedded_assets.rs:180-213
Deployment and CLI Integration
The storage system is tightly integrated with the loco CLI, particularly when generating deployment artifacts.
Docker Deployment
When generating a Docker deployment via cargo loco generate deployment, the system detects static asset configurations. If static assets are enabled, the generator automatically includes the necessary COPY commands in the Dockerfile to ensure assets are present in the final image.
Sources: src/cli.rs:374-398, docs-site/content/blog/frontend-website.md:120-130
Environment Awareness
The storage system respects the LOCO_ENV variable. In production, it may be configured to serve precompressed files or use a different path (e.g., frontend/dist/frontend/browser for Angular apps) compared to development.
Sources: docs-site/content/blog/angular-frontend.md:76-85, src/cli.rs:610-614
Summary
The Loco Storage System provides a flexible abstraction for file management, bridging the gap between local development and cloud-native production environments. By supporting local disk, cloud providers, and embedded assets, it enables the "One Person Framework" goal of simplified deployment while maintaining high performance through efficient static asset serving and middleware integration.
Sources: README.md:65-67, docs-site/content/blog/hello-world.md:92-95