local-dev-serve-troubleshooting

localtaskrepo's avatarfrom localtaskrepo

Use this to run and debug the UI + server locally (Vite dev server, `lotar serve`, ports, SSE).

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026
[Debugging]

When & Why to Use This Skill

This Claude skill streamlines the local development and troubleshooting process for full-stack applications involving Vite and Rust-based servers. It provides standardized procedures for environment setup, port configuration management, and diagnosing connectivity issues between the UI and backend services.

Use Cases

  • Local Environment Orchestration: Quickly launch and synchronize the Vite development server and Rust backend using optimized command sequences and correct port flags.
  • UI-Backend Connectivity Troubleshooting: Diagnose and resolve issues where the UI fails to update by verifying Server-Sent Events (SSE) connections and monitoring API event streams.
  • API Contract Validation: Debug REST handlers and ensure local development stays in sync with OpenAPI specifications and contract changes.
  • Production Simulation: Build and run production-ready static assets and release binaries locally to identify environment-specific bugs before deployment.
  • Advanced Logging & Traceability: Enable and interpret debug-level logs to trace server behavior and resolve complex runtime errors during local iterations.
namelocal-dev-serve-troubleshooting
descriptionUse this to run and debug the UI + server locally (Vite dev server, `lotar serve`, ports, SSE).

Common local dev setups

UI fast loop (Vite dev server)

  • Start UI:

    • npm run dev

  • In another terminal, start the Rust server:

    • cargo run -- serve --port 8080

Notes:

  • lotar serve port must be set with --port (the short -p is reserved for the global --project flag).
    • Correct: lotar serve --port 9000
    • Also accepted: lotar serve 9000 (positional port; kept for backward compatibility)
    • Incorrect (sets project, not port): lotar serve -p 9000
    • See: docs/help/serve.md

Production-like UI (embedded/static bundle)

  • Build web assets:
    • npm run build:web
  • Build the binary:
    • cargo build --release
  • Run:
    • ./target/release/lotar serve --port 8080

Debugging tips

  • If the UI isn’t updating, confirm SSE is connected (GET /api/events). See docs/help/sse.md.
  • If you’re working on REST handlers, use docs/help/api-quick-reference.md and keep docs/openapi.json in sync for contract changes.
  • When chasing server behavior, enable logs:
    • RUST_LOG=debug cargo run -- serve --port 8080

Safety

  • Treat .env* and local config as sensitive; don’t paste secrets/PII into logs/issues.