Crate leptos_store 

leptos-store

Enterprise-grade, type-enforced state management for Leptos.

This crate provides a structured, SSR-safe state management architecture inspired by Vuex and Pinia, translated into idiomatic Rust for Leptos.

Core Concepts

Each store is a domain module composed of:

1. State - Read-only externally, reactive data container
2. Getters - Derived, read-only computed values
3. Mutators - Pure, synchronous state mutations
4. Actions - Synchronous orchestration with side effects
5. Async Actions - Asynchronous orchestration

Mutation Rules

Layer	Can Write State	Async	Side Effects
Components	❌	❌	❌
Getters	❌	❌	❌
Mutators	✅	❌	❌
Actions	❌	❌	✅
Async Actions	❌	✅	✅

Only mutators may write state.

Feature Flags

Feature	Default	Description
ssr	✅ Yes	Server-side rendering support
hydrate	❌ No	SSR hydration with automatic state serialization
csr	❌ No	Client-side rendering only

Choosing Features

• CSR only (SPA): Use features = ["csr"]
• SSR without hydration: Use default features (ssr)
• Full SSR with hydration: Use ssr on server, hydrate on client

Why is hydrate opt-in?

The hydrate feature adds:

• serde and serde_json for state serialization
• web-sys and wasm-bindgen for DOM access
• Approximately 50KB to your WASM bundle

If you don’t need state transfer from server to client, you can skip this overhead.

Available Macros

Macro	Purpose	Feature
define_state!	Define state structs with default values	-
define_hydratable_state!	Define state with serde derives	hydrate
define_action!	Define synchronous action structs	-
define_async_action!	Define async action structs with error types	-
impl_store!	Implement Store trait for an existing type	-
impl_hydratable_store!	Implement HydratableStore trait	hydrate
store!	Complete store definition in one macro	-

See the macros module for detailed documentation and examples.

Hydration Support

When building full SSR applications where state needs to transfer from server to client, enable the hydrate feature:

[dependencies]
leptos-store = { version = "0.1", default-features = false }

[features]
ssr = ["leptos-store/ssr"]
hydrate = ["leptos-store/hydrate"]

This enables:

• HydratableStore trait for state serialization
• provide_hydrated_store() for server-side state embedding
• use_hydrated_store() for client-side state recovery

See the hydration module (requires hydrate feature) for implementation details.

Example

use leptos::prelude::*;
use leptos_store::prelude::*;

// Define your state
#[derive(Clone, Debug, Default)]
pub struct CounterState {
    pub count: i32,
}

// Define your store
#[derive(Clone)]
pub struct CounterStore {
    state: RwSignal<CounterState>,
}

impl Store for CounterStore {
    type State = CounterState;

    fn state(&self) -> ReadSignal<Self::State> {
        self.state.read_only()
    }
}

// Define mutators
impl CounterStore {
    pub fn increment(&self) {
        self.state.update(|s| s.count += 1);
    }

    pub fn decrement(&self) {
        self.state.update(|s| s.count -= 1);
    }
}

Re-exports

pub use prelude::*;

Modules

async

Async actions support for stores.

context

Context management for stores.

hydrationhydrate

Hydration support for SSR stores.

macros

Macros for store definition.

prelude

Prelude module - re-exports all commonly used types and traits.

store

Core store traits and types.

Macros

define_action

Define a synchronous action struct.

define_async_action

Define an async action struct with associated result types.

define_getter

Macro to define a getter function inside an impl block.

define_hydratable_statehydrate

Define a hydratable state struct with serde derives.

define_mutator

Macro to define a mutator function inside an impl block.

define_state

Define a state struct with optional default values.

impl_hydratable_storehydrate

Implement the HydratableStore trait for a store type.

impl_store

Implement the Store trait for an existing type.

store

Define a complete store with state, getters, and mutators in one macro.