leptos-store

Enterprise-grade, type-enforced state management for Leptos

Overview

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

Leptos provides excellent low-level primitives (signals, context, resources), but intentionally does not define a canonical, scalable state architecture. At scale, this absence can create challenges for large teams, enterprise governance, long-lived applications, SSR safety, and state auditing unless additional architectural patterns are introduced.

leptos-store exists to solve structure, not reactivity.

Features

• 🏗️ Global, namespaced stores - Clear domain boundaries
• 🔒 Predictable mutation flow - Only mutators can write state
• 🌐 First-class SSR support - Works seamlessly with server-side rendering
• 💧 SSR Hydration - Automatic state serialization and hydration between server and client
• ⚡ Async-safe actions - Built-in support for async operations
• 🔧 Compile-time enforcement - Catch errors at compile time, not runtime
• 📦 Zero magic - No hidden executors or runtime reflection

Installation

Add to your Cargo.toml:

[dependencies]
leptos-store = "0.1"
leptos = "0.8"

Feature Flags

Basic Usage (SSR without Hydration)

The ssr feature is enabled by default. For basic SSR without state hydration:

[dependencies]
leptos-store = "0.1"

Full SSR with Hydration (Recommended for Production)

For full SSR applications where state needs to transfer from server to client, enable the hydrate feature. This requires different features for server and client builds:

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

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

The hydrate feature enables:

• HydratableStore trait for state serialization
• provide_hydrated_store() - Server-side state embedding
• use_hydrated_store() - Client-side state recovery
• Automatic JSON serialization via serde

Client-Side Only

For SPAs without server rendering:

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

Quick Start

Define Your Store

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 CounterStore {
    pub fn new() -> Self {
        Self {
            state: RwSignal::new(CounterState::default()),
        }
    }

    // Getters - derived, read-only values
    pub fn doubled(&self) -> i32 {
        self.state.with(|s| s.count * 2)
    }

    // Mutators - pure, synchronous state changes
    pub fn increment(&self) {
        self.state.update(|s| s.count += 1);
    }

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

    pub fn set_count(&self, value: i32) {
        self.state.update(|s| s.count = value);
    }
}

impl Store for CounterStore {
    type State = CounterState;

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

Use in Components

#[component]
pub fn App() -> impl IntoView {
    // Provide store to component tree
    let store = CounterStore::new();
    provide_store(store);

    view! {
        <Counter />
    }
}

#[component]
fn Counter() -> impl IntoView {
    let store = use_store::<CounterStore>();

    view! {
        <div>
            <p>"Count: " {move || store.state().get().count}</p>
            <p>"Doubled: " {move || store.doubled()}</p>
            <button on:click=move |_| store.increment()>"+"</button>
            <button on:click=move |_| store.decrement()>"-"</button>
        </div>
    }
}

Using the store! Macro

For less boilerplate, use the declarative macro:

use leptos_store::store;

store! {
    pub CounterStore {
        state CounterState {
            count: i32 = 0,
        }

        getters {
            doubled(this) -> i32 {
                this.read(|s| s.count * 2)
            }
        }

        mutators {
            increment(this) {
                this.mutate(|s| s.count += 1);
            }
            decrement(this) {
                this.mutate(|s| s.count -= 1);
            }
            set_count(this, value: i32) {
                this.mutate(|s| s.count = value);
            }
        }
    }
}

Note: Use this (or any identifier) instead of self in getter/mutator bodies due to Rust 2024 macro hygiene rules. The macro provides this.read() for getters and this.mutate() for mutators.

Available Macros

define_state! - State with Defaults

use leptos_store::define_state;

define_state! {
    #[derive(Clone, Debug, PartialEq)]
    pub struct UserState {
        name: String,                    // Uses String::default()
        email: Option<String>,           // Uses None
        age: u32 = 0,                    // Explicit default
        active: bool = true,             // Explicit default
    }
}

let user = UserState::default();
assert_eq!(user.name, "");
assert!(user.active);

define_action! - Synchronous Actions

use leptos_store::define_action;

define_action! {
    /// Updates user profile information
    #[derive(Debug, Clone)]
    pub UpdateProfileAction {
        user_id: String,
        name: Option<String>,
        email: Option<String>,
    }
}

let action = UpdateProfileAction::new(
    "user_123".to_string(),
    Some("John Doe".to_string()),
    None,
);

define_async_action! - Async Actions with Error Types

use leptos_store::define_async_action;

// Define your error type
#[derive(Debug, Clone)]
enum ApiError {
    Network(String),
    NotFound,
    Unauthorized,
}

// Define the async action
define_async_action! {
    /// Fetches user data from the API
    #[derive(Debug, Clone)]
    pub FetchUserAction {
        user_id: String,
        include_profile: bool,
    } -> Result<UserData, ApiError>
}

let action = FetchUserAction::new("user_123".to_string(), true);

// Helper methods for documentation
assert!(FetchUserAction::result_type_description().contains("Result"));
assert_eq!(FetchUserAction::output_type_name(), "UserData");
assert_eq!(FetchUserAction::error_type_name(), "ApiError");

impl_store! - Quick Store Trait Implementation

use leptos::prelude::*;
use leptos_store::{impl_store, store::Store};

#[derive(Clone, Default)]
struct CartState {
    items: Vec<String>,
    total: f64,
}

#[derive(Clone)]
struct CartStore {
    state: RwSignal<CartState>,
}

// One-liner to implement Store trait
impl_store!(CartStore, CartState, state);

Conceptual Model

Each store is a domain module composed of:

Only mutators may write state. This is the core principle that ensures predictability.

Advanced Usage

Async Actions

use leptos_store::prelude::*;

pub struct LoginAction {
    pub email: String,
    pub password: String,
}

impl AsyncAction<AuthStore> for LoginAction {
    type Output = AuthToken;
    type Error = AuthError;

    async fn execute(&self, store: &AuthStore) -> ActionResult<Self::Output, Self::Error> {
        // Perform async operation
        let token = auth_api::login(&self.email, &self.password).await?;
        
        // Dispatch mutation
        store.set_authenticated(true, token.clone());
        
        Ok(token)
    }
}

Scoped Stores

For multiple instances of the same store type:

// Provide scoped stores with unique IDs
provide_scoped_store::<CounterStore, 1>(counter1);
provide_scoped_store::<CounterStore, 2>(counter2);

// Access scoped stores
let counter1 = use_scoped_store::<CounterStore, 1>();
let counter2 = use_scoped_store::<CounterStore, 2>();

Store Registry

For debugging and hot-reloading:

let mut registry = StoreRegistry::new();
registry.register(my_store)?;

// Later...
let store = registry.get::<MyStore>();

SSR Hydration

For full SSR applications, implement HydratableStore to enable automatic state transfer from server to client:

use leptos::prelude::*;
use leptos_store::prelude::*;
use serde::{Serialize, Deserialize};

// State must derive Serialize and Deserialize
#[derive(Clone, Debug, Default, Serialize, Deserialize)]
pub struct TokenState {
    pub tokens: Vec<Token>,
    pub loading: bool,
}

#[derive(Clone)]
pub struct TokenStore {
    state: RwSignal<TokenState>,
}

impl Store for TokenStore {
    type State = TokenState;
    fn state(&self) -> ReadSignal<Self::State> {
        self.state.read_only()
    }
}

// Implement HydratableStore for SSR hydration
#[cfg(feature = "hydrate")]
impl HydratableStore for TokenStore {
    fn serialize_state(&self) -> Result<String, StoreHydrationError> {
        serde_json::to_string(&self.state.get())
            .map_err(|e| StoreHydrationError::Serialization(e.to_string()))
    }

    fn from_hydrated_state(data: &str) -> Result<Self, StoreHydrationError> {
        let state: TokenState = serde_json::from_str(data)
            .map_err(|e| StoreHydrationError::Deserialization(e.to_string()))?;
        Ok(Self { state: RwSignal::new(state) })
    }

    fn store_key() -> &'static str {
        "token_store"
    }
}

Or use the impl_hydratable_store! macro for less boilerplate:

use leptos_store::impl_hydratable_store;

impl_hydratable_store!(TokenStore, TokenState, state, "token_store");

Server-side (SSR):

// Provide store and render hydration script
let store = TokenStore::new_with_data(tokens);
let hydration_script = provide_hydrated_store(store);

view! {
    {hydration_script}
    <App/>
}

Client-side (Hydration):

// Automatically hydrate from server-rendered state
let store = use_hydrated_store::<TokenStore>();

Design Philosophy

Convention over Primitives

Instead of giving you raw signals and hoping for the best, leptos-store provides a structured architecture that scales.

Compile-time Enforcement

The type system prevents invalid state transitions. If it compiles, it follows the rules.

SSR-First Design

Every feature is designed with server-side rendering in mind. No hydration mismatches.

Examples

See the examples/ directory for complete examples:

• counter-example - Simple counter using the store! macro with increment/decrement
• auth-store-example - User authentication flow with login/logout
• token-explorer-example - Full SSR with hydration - Real-time Solana token explorer using Jupiter API

Running Examples

# List all available examples
make examples-list

# Run a specific example (SSR mode with cargo-leptos)
make run NAME=auth-store-example
make run NAME=token-explorer-example

# Build an example
make build-example NAME=token-explorer-example

Token Explorer Example

The token-explorer-example demonstrates full SSR hydration:

• 🌐 Server-side data fetching from Jupiter API
• 💧 Automatic state hydration to client
• 🔄 Client-side polling for real-time updates
• 🔍 Reactive filtering and sorting
• 🎨 Beautiful token card UI

# Run the token explorer
make run NAME=token-explorer-example

# Opens at http://127.0.0.1:3005

Contributing

We welcome contributions! See AUTHORING.md for:

• Development setup and workflow
• Project structure and architecture
• Testing and code quality guidelines
• Publishing releases

# Quick start for contributors
git clone https://github.com/your-org/leptos-store.git
cd leptos-store
make check   # Verify setup
make test    # Run tests
make help    # See all commands

License and Attribution

leptos-store is licensed under the Apache License, Version 2.0.

You are free to use, modify, and distribute this software, including for commercial purposes, provided that you retain the license text and the NOTICE file as required by the Apache 2.0 License.

This software is provided "AS IS", without warranty of any kind. The author is not liable for any damages arising from its use.