Single Page Applications (React/Angular)
Relevant source files
The following files were used as context for generating this wiki page:
Loco supports the integration of modern Single Page Applications (SPA) such as React and Angular by providing mechanisms to serve static assets and proxy API requests. The framework allows developers to maintain a clear separation between the frontend (Client-side rendering) and the backend REST API while providing a unified deployment model where the Rust binary serves the compiled frontend.
Sources: docs-site/content/blog/frontend-website.md:7-14, snipdoc.yml:30-41
Project Initialization and Frontend Scaffolding
When starting a new project that requires a client-side frontend, the Loco CLI provides a guided process to set up the necessary structure. Choosing the "SaaS app with client side rendering" option prepares the project for an external frontend.
The CLI generates a dedicated frontend/ directory where the SPA logic resides. By default, Loco's SaaS starter may include a Vite-based React setup, but it can be replaced with other frameworks like Angular.
Sources: snipdoc.yml:25-36, docs-site/content/blog/frontend-website.md:25-32, docs-site/content/blog/angular-frontend.md:17-25
Framework Integration
React (Vite/Rsbuild)
React applications in Loco are typically managed using Vite or Rsbuild. The standard workflow involves using npm create vite@latest to initialize the frontend within the Loco project structure.
Key tools used in the React frontend:
- TypeScript: For typed JavaScript development.
- Rsbuild/Vite: For high-performance bundling.
- Axios/React Query: For managing API state and communication.
Sources: loco-new/base_template/frontend/README.md:3-10, docs-site/content/blog/frontend-website.md:65-75
Angular
Angular integration requires custom Dockerfile modifications to include the Angular CLI and Node.js in the development environment. Developers must replace the default React-based frontend with an Angular project using ng new frontend.
Sources: docs-site/content/blog/angular-frontend.md:31-50, docs-site/content/blog/angular-frontend.md:76-78
Asset Serving Configuration
To serve the SPA via Loco, the static middleware must be configured in the environment settings (e.g., config/development.yaml). This allows the Rust server to handle requests for static files and provide a fallback for client-side routing.
| Configuration Key | Purpose | Example Value |
|---|---|---|
server.middlewares.static.enable | Toggles static asset serving | true |
server.middlewares.static.must_exist | Ensures the path exists on startup | true |
server.middlewares.static.folder.uri | The base URI for static assets | "/" |
server.middlewares.static.folder.path | Local filesystem path to build artifacts | "frontend/dist" |
server.middlewares.static.fallback | HTML file for SPA routing fallback | "frontend/dist/index.html" |
Sources: docs-site/content/blog/frontend-website.md:104-112, docs-site/content/blog/angular-frontend.md:88-94
Handling Fallback Priority
A critical implementation detail is the interaction between the fallback middleware and the static middleware. If the global fallback middleware is enabled, it may take priority over static assets, preventing them from being served.
Sources: docs-site/content/blog/frontend-website.md:118-125
API Routing and Development Workflow
To avoid conflicts between SPA routes and REST API endpoints, it is recommended to prefix all backend routes.
- API Prefixing: In
src/app.rs, apply.prefix("/api")toAppRoutes. - Hot Reloading: Use
cargo-watchto ignore thefrontenddirectory while watching Rust source files to prevent unnecessary server restarts during frontend development. - Frontend Dev Server: Run
pnpm devorng serveseparately during development to utilize Vite/Angular HMR.
Production Deployment
In production, the SPA is built into static files, and Loco serves them directly.
- Build: Run
pnpm buildorng build. - Dockerization: The
cargo loco generate deploymentcommand creates a Dockerfile that detects static assets and includes the build directory in the final image. - Execution: The Loco binary runs in
productionmode, serving the UI and API from a single port.
Sources: docs-site/content/blog/frontend-website.md:154-156, docs-site/content/blog/frontend-website.md:164-168, docs-site/config.toml:139-147
Summary
Single Page Applications in Loco leverage the framework's static asset middleware to provide a seamless full-stack experience. By configuring specific folder paths and fallback mechanisms, developers can deploy complex React or Angular interfaces powered by a high-performance Rust REST API.