Welcome to Storion

Storion is a reactive state management library for React that automatically tracks what state you use and only updates when those values change.

No manual selectors. No dependency arrays. Just write natural code.

~4KB minified • Zero dependencies • TypeScript first

---

Prerequisites

Before starting, you should be comfortable with:

• React fundamentals — Components, hooks (useState, useEffect), props
• TypeScript basics — Types, interfaces, generics (optional but recommended)
• npm/pnpm/yarn — Installing packages and running scripts

New to React?

Check out the official React docs first. Storion builds on React's mental model.

---

Choose Your Path

🚀 Quick Start

5 minutes — Jump straight into code

Perfect if you learn by doing. Get a working store up and running immediately.

1. Getting Started — Install and build your first store
2. Counter Example — See the complete code

📖 Concept First

30 minutes — Understand the architecture

Best if you want to know the "why" before the "how".

1. Core Concepts — Architecture and design philosophy
2. Stores — How state and actions work together
3. Getting Started — Then build something

🔧 API Reference

Reference as needed — For experienced developers

Already know state management? Jump to what you need:

• API Reference — Complete API documentation
• Examples — Common patterns with code
• Live Demos — Interactive showcases

---

The Problem We Solve

Most state libraries require manual dependency tracking:

// ❌ Redux/Zustand: Specify exactly what you need
const name = useSelector((state) => state.user.name);
const email = useSelector((state) => state.user.email);

// Forget a selector? Stale data.
// Select too much? Extra re-renders.
// Return new object? Infinite loops.

Storion uses automatic tracking:

// ✅ Storion: Just use state naturally
const { name, email } = useStore(({ get }) => {
  const [state] = get(userStore);
  return { name: state.name, email: state.email };
});

// Storion tracks that you accessed `name` and `email`
// Component re-renders ONLY when those values change

Comparison

Scenario	Redux/Zustand	Storion
Return new object	❌ Causes infinite re-render	✅ Works correctly
Computed values	❌ Need manual memoization	✅ Automatic
Conditional access	❌ Manual dependency handling	✅ Automatic
Multiple properties	❌ Need shallowEqual	✅ Just works
Nested state access	❌ Need structured selectors	✅ Access naturally

---

Key Features

🎯 Auto-Tracking

No manual dependency arrays. Read state naturally and Storion tracks it for you.

🔒 Type-Safe

Full TypeScript inference for state, actions, and selectors. No explicit generics needed.

⚡ Fine-Grained

Only re-renders components that actually use the changed data. No wasted renders.

🧩 Composable

Stores can access other stores. Build complex state from simple, focused pieces.

⏳ First-Class Async

Built-in loading states, error handling, cancellation, and retry. No extra libraries.

🧪 Testable

Dependency injection makes testing easy. Mock services, isolate stores, test in Node.

---

Progressive Complexity

Storion grows with your app. Start simple, add complexity only when needed:

Stage	What You Learn	Features Used
Beginner	Basic state management	store(), useStore(), direct mutation
Growing	Multiple stores	Cross-store get(), update()
Complex	Async operations	async(), focus(), trigger()
Enterprise	Architecture	Middleware, meta, persistence, DI

You don't need everything

Most apps only need stores, actions, and useStore. Advanced features exist for when your app needs them.

---

Guide Structure

Getting Started

• Getting Started — Installation and first store
• Core Concepts — Architecture overview

State & Actions

• Stores — Defining state and actions
• Actions — Functions that modify state
• Reactivity — How auto-tracking works

Async & Effects

• Effects — Side effects that react to state
• Async — Loading states and data fetching

Advanced

• Meta — Annotations for middleware
• Middleware — Cross-cutting concerns
• Persistence — Saving state to storage
• Dependency Injection — Services and testing
• Testing — Unit and integration tests
• DevTools — Debugging and inspection

React Integration

• useStore — The main React hook
• StoreProvider — Container isolation
• withStore — HOC for class components

---

Quick Links

📖Getting StartedYour first store in 5 minutes📚API ReferenceComplete documentation💻Live DemosSee Storion in action🧩ExamplesCommon patterns with code

---

Need Help?

• 🐛 Found a bug? Open an issue
• 💬 Have questions? Start a discussion
• 📖 Docs unclear? Help us improve by suggesting edits

---

Ready to start? Let's build your first store →