Rustelo/info/leptos_serve_fix.md

# Leptos Serve Multiple Binary Targets Fix

## Problem

When running `cargo leptos serve`, the following error occurred:

```
Error:
   0: at `/Users/jesusperezlorenzo/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/cargo-leptos-0.2.35/src/lib.rs:43:76`
   1: at `/Users/jesusperezlorenzo/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/cargo-leptos-0.2.35/src/config/mod.rs:58:84`
   2: Several bin targets found for member "server", please specify which one to use with: [[workspace.metadata.leptos]] bin-target = "name"
```

## Root Cause

The `server` crate had multiple binary targets:
1. `server` (from `src/main.rs`) - the main application server
2. `config_tool` (from `src/bin/config_tool.rs`) - configuration management utility

Cargo-leptos couldn't determine which binary target to use for the leptos serve command.

## Solution

### 1. Added bin-target specification to workspace configuration

In `template/Cargo.toml`, added the `bin-target` specification:

```toml
[[workspace.metadata.leptos]]
# The name used by wasm-bindgen/cargo-leptos for the JS/WASM bundle. Defaults to the crate name
output-name = "website"
# Specify which binary target to use (fixes multiple bin targets error)
bin-target = "server"
# ... rest of configuration
```

### 2. Added explicit binary target definitions

In `template/server/Cargo.toml`, added explicit binary targets:

```toml
# Binary targets
[[bin]]
name = "server"
path = "src/main.rs"

[[bin]]
name = "config_tool"
path = "src/bin/config_tool.rs"
```

### 3. Fixed tokio LocalSet runtime issue

Added proper LocalSet configuration to handle leptos local tasks:

**In `template/server/src/main.rs`:**
```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a LocalSet to handle leptos local tasks
    let local = tokio::task::LocalSet::new();
    local.run_until(run_server()).await
}

async fn run_server() -> Result<(), Box<dyn std::error::Error>> {
    // All server logic moved here
    // ...
}
```

### 4. Fixed WASM compatibility issue

Added the `js` feature to uuid dependencies for WASM target compatibility:

**In `template/server/Cargo.toml`:**
```toml
uuid = { version = "1.17", features = ["v4", "serde", "js"], optional = true }
```

**In `template/shared/Cargo.toml`:**
```toml
uuid = { version = "1.17", features = ["v4", "serde", "js"] }
```

## Verification

After applying the fixes:

1. ✅ `cargo leptos serve` no longer shows the "Several bin targets found" error
2. ✅ No more "spawn_local called from outside of a task::LocalSet" runtime panics
3. ✅ `cargo leptos build` completes successfully
4. ✅ WASM compilation works without uuid randomness errors
5. ✅ All project tests continue to pass

## Usage

Now you can use cargo-leptos commands without issues:

```bash
# Start development server
cargo leptos serve

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

# Build the project
cargo leptos build

# Build for production
cargo leptos build --release

# Watch for changes
cargo leptos watch
```

## Files Modified

1. **`template/Cargo.toml`** - Added `bin-target = "server"` to leptos metadata
2. **`template/server/src/main.rs`** - Added LocalSet configuration for leptos runtime
3. **`template/server/Cargo.toml`** - Added explicit binary targets and fixed uuid features
4. **`template/shared/Cargo.toml`** - Fixed uuid features for WASM compatibility
5. **`template/README.md`** - Added leptos serve documentation
6. **`template/docs/LEPTOS_SERVE.md`** - Created comprehensive leptos documentation

## Key Configuration

The critical fix is in the workspace `Cargo.toml`:

```toml
[[workspace.metadata.leptos]]
bin-target = "server"  # This line fixes the multiple targets error
bin-package = "server"
lib-package = "client"
```

This tells cargo-leptos to use the `server` binary target (from `src/main.rs`) instead of the `config_tool` binary when running leptos commands.

## Additional Benefits

The fixes provide:
- Clearer project structure documentation
- Better IDE support for binary targets
- More predictable build behavior
- Proper leptos runtime context for local task spawning
- Enhanced error handling and graceful shutdown

## Testing

To verify the fix works:

```bash
# Should work without errors
cargo leptos serve --help

# Should build successfully
cargo leptos build

# Should start development server
cargo leptos serve -- -c config.dev.toml
```

## Related Documentation

- [Leptos Serve Documentation](./docs/LEPTOS_SERVE.md)
- [Cargo Leptos Documentation](https://github.com/leptos-rs/cargo-leptos)
- [Leptos Framework Documentation](https://leptos.dev/)