HadiCherkaoui/leptos

Leptos Web Framework Skill

This skill enforces correct, idiomatic Leptos 0.7+ development. It ensures all Leptos code follows the framework's reactive model, component patterns, SSR best practices, and avoids common pitfalls.

Mandatory Workflow

This skill MUST be invoked for ANY Leptos-related action, including:

• Creating or modifying components (#[component], #[island])
• Working with signals, memos, effects, or stores
• Writing server functions (#[server])
• Configuring routing (leptos_router)
• Setting up SSR, hydration, or deployment

Which guideline to read and when

Before writing or modifying Leptos code, load ONLY the guideline files that apply to the requested task, using segmented reading (offset and limit) when needed.

Guidelines and when they apply

1. 01_reactivity.md

Use when working on:

• Creating or reading signals (signal(), RwSignal, ReadSignal, WriteSignal)
• Signal methods (.get(), .set(), .read(), .write(), .with(), .update())
• Derived signals (closures that read other signals)
• Memos (Memo::new) and when to use memos vs derived signals
• Effects (Effect::new, Effect::watch) and when to use/avoid them
• The reactive ownership model and signal lifecycle
• ArcRwSignal for collections
• Global state management (provide_context, use_context, stores)

2. 02_components.md

Use when working on:

• The view! macro syntax (RSX) and how it differs from HTML
• Creating components with #[component]
• Component props (#[prop(optional)], #[prop(into)], #[prop(default)])
• Dynamic attributes (class:, style:, prop:, attr:, on:)
• Passing children to components (Children, ChildrenFn, ChildrenFragment)
• Parent-child communication patterns
• Attribute spreading and slots
• The builder syntax (alternative to view! macro)

3. 03_control_flow_and_forms.md

Use when working on:

• Control flow in views (if/else, match, <Show/>, Option<T>)
• Type erasure for heterogeneous branches (.into_any(), Either)
• Error handling (<ErrorBoundary/>, Result<T,E> in views)
• Controlled inputs (on:input, prop:value, bind:)
• Uncontrolled inputs (NodeRef)
• <textarea>, <select> handling
• Iteration (<For/>, <ForEnumerate/>, .collect_view())
• Complex data iteration (nested signals, stores, memoized slices)

4. 04_async.md

Use when working on:

• Loading async data with Resource, LocalResource, OnceResource
• <Suspense/> for loading states
• <Transition/> for non-flickering reloads
• <Await/> for one-shot futures
• Suspend::new for awaiting resources without null-checking
• Actions (Action::new) for mutations
• ServerAction for server function mutations
• Optimistic UI patterns
• spawn_local for ad-hoc async work

5. 05_router.md

Use when working on:

• Router setup (<Router>, <Routes>, <Route>)
• Route path patterns (path!() macro, params, wildcards)
• Nested routing (<ParentRoute>, <Outlet/>)
• Route params and query strings (use_params, use_query, Params derive)
• Client-side navigation (<A/>, use_navigate)
• URL-based forms (<Form/>)
• Metadata (<Title/>, <Meta/>, <Html/>, <Body/>)
• Styling approaches (Tailwind, Stylers, Stylance, plain CSS)
• JavaScript interop (web_sys, NodeRef, wasm-bindgen)

6. 06_server.md

Use when working on:

• Server functions (#[server] macro)
• ServerFnError and custom error types
• Extractors (Actix/Axum) in server functions
• Response manipulation (ResponseOptions, redirect)
• Progressive enhancement and <ActionForm/>
• Complex/nested form inputs with serde_qs
• Server function security considerations
• Providing server state via context

7. 07_ssr.md

Use when working on:

• cargo-leptos setup and configuration
• The lifecycle of a page load (SSR -> hydration)
• SSR modes (out-of-order streaming, in-order, async, sync, partially-blocked)
• Resource::new_blocking for SEO-critical content
• Common hydration bugs and how to avoid them
• Server/client code boundaries (cfg!, Effect::new for client-only code)
• Invalid HTML causing hydration errors

8. 08_deployment.md

Use when working on:

• Deploying CSR apps (Trunk, GitHub Pages, Netlify, Vercel)
• Deploying SSR apps (Docker, Fly.io, AWS Lambda, Deno)
• Non-root path deployment (base prop on Router)
• WASM binary size optimization (opt-level, lto, codegen-units, build-std)
• Code splitting (#[lazy], #[lazy_route])
• Islands architecture (#[island] macro)
• Feature gating (ssr vs hydrate features)

Core Rules

1. Load the necessary guideline files BEFORE generating any Leptos code.
2. Components are setup functions that run ONCE -- they are NOT render functions.
3. For values to be reactive in the view, they must be signals or closures that capture signals.
4. Use prop:value for current input values, NOT the value attribute.
5. Always use <tbody> in tables to prevent hydration bugs.
6. Server functions are public API endpoints -- never return private data without auth.
7. Use ArcRwSignal (not RwSignal) for signals stored in collections.
8. Prefer derived signals for cheap computations; use Memo only for expensive ones.
9. Never write to a signal inside an effect that reads another signal -- use derived signals instead.
10. Always include <Outlet/> in parent route components for nested routing.