Guide

This guide provides a step-by-step approach to setting up Stately, from initial installation to production-ready configurations.

The documentation is organized by task:

• Start with a single store.
• Add plugins to solve specific state challenges.
• Implement SSR-safe patterns for SvelteKit.
• Use the reference pages for detailed API contracts.

Installation

pnpm add @selfagency/stately svelte

Defining Your First Store

To get started, create a state manager and a store definition, then instantiate the store:

import { createStateManager, defineStore } from '@selfagency/stately';

const manager = createStateManager();

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    doubleCount(state) {
      return state.count * 2;
    }
  },
  actions: {
    increment() {
      this.count += 1;
    }
  }
});

const counter = useCounterStore(manager);
counter.increment();

---

Navigation by Task

Core Concepts

• Defining Stores — Learn about option stores, setup stores, patches, and subscriptions.
• Examples & Recipes — Practical, copyable patterns for common use cases.

Adding Advanced Behavior

• Plugins — A guide to selecting and implementing plugins.
• State Machines (FSM) — Model explicit workflows and state transitions.
• Validation — Ensure state consistency by rejecting invalid updates.

SSR & SvelteKit

• SSR & SvelteKit — Best practices for request-scoped managers and avoiding memory leaks.
• SvelteKit Data Loading — Hydrate stores from load functions safely.

Tooling & Maintenance

• Inspector — Set up the development drawer and Vite integration.
• Troubleshooting — Solutions for common implementation mistakes.
• Testing & Releases — Guidance on validation and release workflows.

Migration

• Migration from Pinia — A specialized guide for developers transitioning from Vue/Pinia.

---

Documentation Strategy

• Use the Guide when you want to understand recommended patterns and architectural trade-offs.
• Use the API Reference when you need exact option shapes, function signatures, or TypeScript definitions.