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`:

```rust
.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:

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

### 2. Including CSS Stylesheets

Add CSS files to `content/public/styles/`:

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

### 3. Loading JavaScript Files

Include JavaScript files from `content/public/scripts/`:

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

### 4. Downloadable Documents

Provide downloadable files:

```html
<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.