Rustelo/info/static_files.md

Static File Serving in Rustelo

Rustelo provides built-in static file serving capabilities that allow you to serve images, PDFs, HTML files, and other static assets directly from the filesystem without any server-side processing.

Overview

Static files are served from the content/public directory and are accessible via the /public/ URL prefix. This feature is implemented using Axum's ServeDir service, which provides efficient static file serving with proper MIME type detection and caching headers.

Configuration

The static file serving is configured in server/src/main.rs:

.nest_service("/public", ServeDir::new("content/public"))

This configuration maps all requests to /public/* to files in the content/public directory.

Directory Structure

content/public/
├── images/          # Image files (PNG, JPG, SVG, etc.)
├── documents/       # PDF files, Word docs, etc.
├── styles/          # CSS stylesheets
├── scripts/         # JavaScript files
├── fonts/           # Web fonts
├── videos/          # Video files
├── downloads/       # Files for download
├── example.html     # Example HTML file
└── README.md        # Documentation

URL Mapping

File Path	Accessible URL
content/public/example.html	/public/example.html
content/public/images/logo.png	/public/images/logo.png
content/public/documents/manual.pdf	/public/documents/manual.pdf
content/public/styles/custom.css	/public/styles/custom.css
content/public/scripts/app.js	/public/scripts/app.js

Supported File Types

The server automatically detects and serves files with appropriate MIME types:

• HTML files (.html, .htm) → text/html
• CSS files (.css) → text/css
• JavaScript files (.js) → application/javascript
• Images (.png, .jpg, .jpeg, .gif, .svg, .webp) → image/*
• PDF documents (.pdf) → application/pdf
• Text files (.txt, .md) → text/plain
• JSON files (.json) → application/json
• XML files (.xml) → application/xml

Usage Examples

1. Serving Images

Place images in content/public/images/ and reference them:

<img src="/public/images/logo.png" alt="Company Logo">

2. Including CSS Stylesheets

Add CSS files to content/public/styles/:

<link rel="stylesheet" href="/public/styles/custom.css">

3. Loading JavaScript Files

Include JavaScript files from content/public/scripts/:

<script src="/public/scripts/app.js"></script>

4. Downloadable Documents

Provide downloadable files:

<a href="/public/documents/user-manual.pdf" download>Download Manual</a>

Features

• Direct File Serving: Files are served exactly as stored, without processing
• MIME Type Detection: Automatic content-type headers based on file extension
• Performance: Efficient serving with proper caching headers
• Security: Files are served read-only with no server-side execution
• Flexibility: Supports any file type with proper MIME mapping

Security Considerations

• Public Access: All files in content/public are publicly accessible
• No Authentication: Files are served without any access control
• No Processing: Files are served as-is, no server-side code execution
• File Permissions: Ensure proper file system permissions are set

Performance Notes

• Files are served directly by the Axum server for optimal performance
• Consider using a CDN for better global performance in production
• Large files should be optimized before placing in the public directory
• Browser caching headers are automatically set for static files

Example Files

The template includes example files to demonstrate the functionality:

• /public/example.html - Complete HTML page with CSS and JavaScript
• /public/styles/custom.css - CSS stylesheet with utility classes
• /public/scripts/example.js - JavaScript file with interactive demos
• /public/README.md - Detailed documentation

Development vs Production

Development

• Files are served directly from the filesystem
• Changes are immediately visible without restart
• No additional caching beyond browser defaults

Production

• Consider using a reverse proxy (nginx) for better static file performance
• Implement CDN for global distribution
• Use compression (gzip/brotli) for better transfer speeds
• Set appropriate cache headers for different file types

Best Practices

1. Organization: Group similar files in subdirectories
2. Naming: Use descriptive, SEO-friendly filenames
3. Optimization: Compress images and minify CSS/JS before deployment
4. Security: Never store sensitive files in the public directory
5. Maintenance: Remove unused files regularly to keep the directory clean

Troubleshooting

File Not Found (404)

• Verify the file exists in content/public
• Check the URL path matches the file path exactly
• Ensure proper file permissions (readable by the server)

Wrong MIME Type

• Check the file extension is recognized
• Verify the file content matches the expected type
• Ensure the file is not corrupted

Permission Denied

• Check file system permissions
• Verify the server process has read access to the directory
• Ensure the file is not locked by another process

Testing

You can test the static file serving by:

1. Starting the server: cargo leptos serve
2. Accessing the example file: http://localhost:3000/public/example.html
3. Using the browser's developer tools to inspect network requests
4. Running the JavaScript test functions in the browser console

The example JavaScript file provides test utilities accessible via StaticFileDemo.test() in the browser console.