Rustelo/docs/leptos-serve.md

# Leptos Serve Documentation

This document explains how to use `cargo leptos serve` with this project and troubleshoot common issues.

## Quick Start

To start the development server with leptos:

```bash
cargo leptos serve
```

To start with a specific configuration file:

```bash
cargo leptos serve -- -c config.dev.toml
```

## Configuration

The leptos configuration is defined in the workspace `Cargo.toml` file under `[[workspace.metadata.leptos]]`:

```toml
[[workspace.metadata.leptos]]
output-name = "website"
bin-target = "server"           # Specifies which binary to use
site-root = "target/site"
site-pkg-dir = "pkg"
assets-dir = "public"
site-addr = "127.0.0.1:3030"
reload-port = 3031
env = "DEV"
bin-features = ["ssr"]
lib-features = ["hydrate"]
name = "website"
bin-package = "server"
lib-package = "client"
```

## Binary Targets

This project has multiple binary targets:
- `server` - Main application server (used by leptos)
- `config_tool` - Configuration management utility

The `bin-target = "server"` specification ensures leptos uses the correct binary.

## Common Commands

### Development Server
```bash
# Start development server
cargo leptos serve

# Start with custom config
cargo leptos serve -- -c config.dev.toml

# Start with environment variables
ROOT_PATH=/custom/path cargo leptos serve
```

### Building
```bash
# Build for development
cargo leptos build

# Build for production
cargo leptos build --release
```

### Watching Files
```bash
# Watch for changes and rebuild automatically
cargo leptos watch
```

## Environment Variables

Leptos respects the same environment variables as the server:

```bash
# Server configuration
ROOT_PATH=/app \
ENVIRONMENT=development \
SERVER_PORT=3030 \
cargo leptos serve
```

## Configuration Files

You can specify different configuration files:

```bash
# Development
cargo leptos serve -- -c config.dev.toml

# Production  
cargo leptos serve -- -c config.prod.toml

# Custom configuration
cargo leptos serve -- -c /path/to/custom.toml
```

## Troubleshooting

### Multiple Binary Targets Error

**Error:**
```
Several bin targets found for member "server", please specify which one to use with: 
[[workspace.metadata.leptos]] bin-target = "name"
```

**Solution:**
This is fixed by specifying `bin-target = "server"` in the workspace configuration.

### LocalSet Runtime Error

**Error:**
```
PANIC: panicked at tokio-1.46.1/src/task/local.rs:420:29:
`spawn_local` called from outside of a `task::LocalSet` or LocalRuntime
```

**Solution:**
This is fixed by wrapping the main server logic in a `tokio::task::LocalSet`. The main function now uses:

```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let local = tokio::task::LocalSet::new();
    local.run_until(run_server()).await
}
```

This provides the proper runtime context for Leptos to spawn local tasks.

### Port Already in Use

**Error:**
```
Error binding to 127.0.0.1:3030: Address already in use
```

**Solutions:**
1. Stop the running server: `pkill -f "target.*server"`
2. Use a different port: Modify `site-addr` in Cargo.toml
3. Set via environment: `SERVER_PORT=3031 cargo leptos serve`

### Configuration File Not Found

**Error:**
```
Failed to load configuration: Missing file: config.toml
```

**Solutions:**
1. Ensure you're in the project root directory
2. Check if the config file exists: `ls -la config*.toml`
3. Use absolute path: `cargo leptos serve -- -c /full/path/to/config.toml`

### Database Connection Issues

If the server fails to start due to database issues:

1. Check database URL in configuration
2. Ensure database is running
3. For development without database:
   ```bash
   cargo leptos serve -- -c config.dev.toml
   ```

## Development Workflow

### Typical Development Setup

1. **Start the development server:**
   ```bash
   cargo leptos serve -- -c config.dev.toml
   ```

2. **In another terminal, start CSS watching (if using Tailwind):**
   ```bash
   npm run dev
   ```

3. **Make changes to your code** - leptos will automatically rebuild and reload

### Common Issues and Solutions

If you encounter runtime panics or errors:

1. **LocalSet Error**: Ensure your main function uses `tokio::task::LocalSet`
2. **Binary Target Error**: Verify `bin-target = "server"` is set in Cargo.toml
3. **WASM Compilation**: Check that uuid has the "js" feature enabled
4. **Environment Variables**: Set `LEPTOS_OUTPUT_NAME=website` if needed

### Project Structure

```
template/
├── Cargo.toml              # Workspace config with leptos metadata
├── config.dev.toml         # Development configuration
├── config.prod.toml        # Production configuration
├── server/
│   ├── Cargo.toml         # Server dependencies and binary targets
│   ├── src/
│   │   ├── main.rs        # Main server binary (used by leptos)
│   │   └── bin/
│   │       └── config_tool.rs  # Additional binary
├── client/                # Frontend Leptos components
└── shared/                # Shared code between client and server
```

## Advanced Usage

### Custom Build Features

You can customize which features are enabled:

```bash
# Build with specific features
cargo leptos build --bin-features "ssr,auth"

# Build lib with specific features  
cargo leptos build --lib-features "hydrate"
```

### Production Deployment

For production builds:

```bash
# Build optimized release
cargo leptos build --release

# The output will be in target/site/
# Deploy the contents of target/site/ to your web server
```

### Custom Server Configuration

You can pass additional arguments to the server:

```bash
# Pass custom server arguments
cargo leptos serve -- -c config.prod.toml --verbose

# With environment variables
ROOT_PATH=/app \
DATABASE_URL=postgresql://... \
cargo leptos serve -- -c config.prod.toml
```

## Integration with Other Tools

### Docker

```dockerfile
FROM rust:latest
WORKDIR /app
COPY . .

# Install cargo-leptos
RUN cargo install cargo-leptos

# Build the project
RUN cargo leptos build --release

ENV ROOT_PATH=/app
ENV ENVIRONMENT=production

EXPOSE 3030
CMD ["cargo", "leptos", "serve", "--", "-c", "config.prod.toml"]
```

### CI/CD

```yaml
# GitHub Actions example
- name: Install cargo-leptos
  run: cargo install cargo-leptos

- name: Build with leptos  
  run: cargo leptos build --release

- name: Test server
  run: |
    ROOT_PATH=/tmp/test \
    cargo leptos serve -- -c config.test.toml &
    sleep 5
    curl http://localhost:3030/health
```

## Related Documentation

- [ROOT_PATH Configuration](./ROOT_PATH_CONFIG.md)
- [Configuration Guide](./CONFIGURATION.md)
- [Deployment Guide](./DEPLOYMENT.md)
- [Leptos Official Documentation](https://leptos.dev/)

## Performance Tips

1. **Use release builds for production:**
   ```bash
   cargo leptos build --release
   ```

2. **Enable compression in production config:**
   ```toml
   [app]
   enable_compression = true
   ```

3. **Optimize asset serving:**
   ```toml
   [static]
   assets_dir = "public"  # Ensure static assets are properly configured
   ```

4. **Monitor reload port conflicts:**
   - Default reload port: 3031
   - Change if needed: `reload-port = 3032` in Cargo.toml

## Recent Fixes

### LocalSet Runtime Fix (v0.1.0)
- **Issue**: `spawn_local` called from outside of a `task::LocalSet` panic
- **Fix**: Main function now uses `tokio::task::LocalSet` for proper Leptos runtime context
- **Impact**: Eliminates runtime panics when using cargo leptos serve

### Multiple Binary Targets Fix (v0.1.0)
- **Issue**: "Several bin targets found" error with cargo-leptos
- **Fix**: Added `bin-target = "server"` to workspace leptos configuration
- **Impact**: cargo leptos commands now work without ambiguity

### WASM Compatibility Fix (v0.1.0)
- **Issue**: uuid compilation errors on wasm32-unknown-unknown target
- **Fix**: Added "js" feature to uuid dependencies
- **Impact**: Clean WASM builds for frontend components