Leptos

Leptos — Rust Reactive Web Playbook

The opinionated build playbook and current-API reference for Leptos full-stack apps. Leptos is fine-grained reactive (signals drive surgical DOM updates — no VDOM, no diffing), and almost every beginner trap comes from forgetting that one fact. This skill encodes the idioms, the ecosystem map (including the eye candy), and the gotchas so you write code that compiles the first time and updates only what changed.

This skill owns the Rust + reactivity + full-stack layer. For the visual layer (premium UI polish, design tokens, anti-slop critique), compose with open-design and design-audit — they emit the design system; this skill implements it in Leptos.

Routing Trigger

Route here when the user is building, editing, debugging, or scaffolding a Leptos app, or choosing anything in the Leptos ecosystem. Single-agent reference + implementation skill (no swarm). If the task is also "make it look premium", run design-audit/open-design for the visual plan and return here to implement it.

Version Anchor & Framework Health (read first — honest open-source insight)

• Current: 0.8.x stable; 0.9.0-alpha in development. The 0.7 "tachys" rewrite replaced the old leptos_reactive crate with reactive_graph (arena-allocated ownership), made the renderer statically typed, deprecated all create_* constructors, and reworked the router. Most Leptos code older than 0.7 is wrong on the current API — don't pattern-match on pre-0.7 blog posts.
• 0.9-alpha adds function-call signal reads (count() instead of count.get()) on stable Rust.
• Maintenance reality: in 2026 the creator (Greg Johnston) announced Leptos is feature-complete and moving to light maintenance (burnout). The framework is stable and production-proven — not rotting — but this drives library selection: prefer crates with independent, active maintainers (Synphonyte, basro/stylance, OpenAnalytics/Leptodon) over single-contributor projects that may stall. See references/ecosystem.md for the live/dead map. Is Leptos still the right choice? That's a real question, not a given — references/alternatives.md is the verified mid-2026 feature analysis of every Rust web-UI option (the only serious "off-Leptos" candidate is Dioxus, for cross-platform reach + funding; for server-rendered CRUD, Axum + Maud/Askama
  • htmx is the lowest-risk answer). Don't rewrite working Leptos apps; do widen the menu for new projects.
• Always verify the exact API against docs.rs/leptos and book.leptos.dev for the version pinned in Cargo.toml. The view! macro and server-fn surface shift between minors; this skill gives idioms, the docs give the signature for your pin.

The Reference Map (progressive disclosure)

Read the SKILL body for the decision; open the matching reference for the code.

Non-Negotiables (the distilled best practice — violate these and it breaks)

1. use leptos::prelude::*; — not use leptos::* (0.7+). Half of "function not found" errors are this.
2. signal() / RwSignal::new() / Memo::new() / Effect::new() — the create_* forms are deprecated.
3. Reactivity lives in closures. {move || count.get()}, not {count.get()}. A bare .get() / if / match in the view body runs once and never updates.
4. Pass the signal, not its value. Props take count (a Signal), never count.get().
5. Signals are Copy (arena IDs) — just move them into closures. Clone the signal (ArcRwSignal) for dynamic collections, never clone the value to "fix" reactivity.
6. Prefer derived signals / Memo over Effect for syncing state. Effects are for the outside world only (DOM, console, storage, network). An effect that writes a signal is almost always a Memo in disguise.
7. <For> needs a stable key (never the index for reorderable lists), and mutable rows need per-row signals or a keyed Store.
8. Feature triad: default = []. ssr, hydrate, csr are mutually exclusive; cargo-leptos selects per target. ["ssr","hydrate"] together = broken build.
9. Gate server-only code with #[cfg(feature = "ssr")] and remember #[server] fns are public HTTP endpoints — never return secrets/un-redacted PII without auth inside the body.
10. Render deterministically across server and client. No web_sys::window(), localStorage, or cfg!(target_arch=...) branching during the initial render — wrap browser-only work in Effect::new. This is the #1 hydration-mismatch cause.

Build Workflow (the path)

1 — Scaffold

Pick a template (full detail + commands in references/tooling.md):

Then drop in the scaffold from assets/project-skeleton.md (feature flags, wasm-release profile, editor + formatter config). This avoids ~80% of first-day build breaks.

2 — Choose the rendering mode

3 — Compose the UI (eye candy → pick a stack)

Three battle-tested starting stacks (full comparison in references/ecosystem.md):

• Fast start: Leptos 0.8 + Tailwind v4 + DaisyUI 5 + leptos-icons + leptos-chartistry.
• Components included: + Thaw UI (Fluent, no Tailwind needed) or Leptodon (Flowbite, commercially backed) + Stylance for scoped overrides + Tailwind Fuse for class merging + leptos-struct-table + leptos_image.
• Design-system ownership: + rust-ui/ui (shadcn-style copy-paste, you own the code) + Stylance + phosphor-leptos.

Reach for leptos-use (100+ reactive hooks, SSR-safe use_window/use_cookie/use_debounce_fn) in every project.

4 — Reactivity discipline

Design state granular (separate signals or a Store<T>, not one mega-struct). Derive with Memo. Lift shared state to the lowest common ancestor or provide_context. See references/reactivity.md.

5 — Data & server boundary

Resource::new(source, fetcher) inside <Suspense> / <Transition>; ServerAction + <ActionForm> for mutations (progressive enhancement — forms work without JS). references/fullstack.md.

6 — Test & perf gate

cargo leptos test (native + wasm-bindgen-test), Playwright end2end/ for flows. Before release: wasm-release profile, wasm-opt, measure target/site/pkg/*.wasm gzip size, consider islands / #[lazy_route]. references/tooling.md.

7 — Persist what you learned (RuVector)

Store reusable Leptos patterns and hard-won fixes so the next session reuses them.

Quality Gate — the "Leptos Smell Test"

Before calling a Leptos change done, scan for these. Any hit = not done (full list in references/pitfalls.md):

• A .get() / if / match sitting in the view! body outside a move || closure → it's static, won't update.
• A prop receiving signal.get() instead of the signal → child never re-renders.
• An Effect::new whose only job is set_b.set(f(a.get())) → replace with a derived signal / Memo.
• <For> keyed by index, or rows whose fields aren't individually reactive → stale/duplicated rows on reorder.
• web_sys::window() / document() / localStorage reached during render (not inside an Effect) → hydration panic on SSR.
• Invalid HTML nesting (<div> in <p>, <tr> without <tbody>) → hydration mismatch.
• ssr/hydrate both active, or server-only imports without #[cfg(feature="ssr")] → build break.
• A #[server] fn returning a secret/token/raw PII without an auth check in the body → data leak.
• Signal::derive(expensive_fn) where the value is read often → no caching; use Memo::new.
• Arena signals created per-item in a growing Vec without ArcRwSignal/.dispose() → leak / disposed-signal panic.

Memory (RuVector)

Per workspace policy, use RuVector MCP tools — never file-based memory.

• Before designing non-trivial reactive state or picking a library, search prior decisions: mcp__claude-flow__memory_search({query: "leptos <topic>", namespace: "project-state", limit: 5}).
• After solving a real trap or settling a stack choice, store a plain-text summary (mcp__claude-flow__memory_store, namespace project-state, upsert: true) — e.g. "Leptos hydration mismatch from <table> without <tbody> — always emit explicit <tbody>". This compounds across the team's Leptos work.

Related Skills / Composition With Sibling Skills