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:

cargo leptos serve

To start with a specific configuration file:

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

Configuration

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

[[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

# 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

# Build for development
cargo leptos build

# Build for production
cargo leptos build --release

Watching Files

# Watch for changes and rebuild automatically
cargo leptos watch

Environment Variables

Leptos respects the same environment variables as the server:

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

Configuration Files

You can specify different configuration files:

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

#[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:

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

Development Workflow

Typical Development Setup

1. Start the development server:

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

2. In another terminal, start CSS watching (if using Tailwind):

   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:

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

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

# 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

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

# 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
• Configuration Guide
• Deployment Guide
• Leptos Official Documentation

Performance Tips

1. Use release builds for production:

   cargo leptos build --release
   

2. Enable compression in production config:

   [app]
   enable_compression = true
   

3. Optimize asset serving:

   [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