reactivestate-a2

A simple and flexible React state management utility combining React's useState and Zustand for local and global state management, with optional persistence support.

GitHub Repository

What is reactivestate-a2?

reactivestate-a2 is a powerful yet simple React state management library that bridges the gap between local component state and global application state. Built on top of Zustand for performance and React hooks for familiarity, it provides a unified API that feels like using useState but with the power of global state management.

Why reactivestate-a2?

Traditional React state management often requires:

• Context providers for global state
• Redux for complex state logic
• Multiple different APIs for local vs global state
• Boilerplate code for persistence
• Complex setup and configuration

reactivestate-a2 solves these problems by:

• Providing a single, familiar API (useState-like)
• Automatically handling global state sharing
• Built-in localStorage persistence
• Zero configuration required
• TypeScript support out of the box
• Minimal bundle size with maximum functionality

Key Benefits

🚀 Familiar API: Works exactly like useState - no learning curve 🌍 Global State: Share state across components with a simple .global() call 💾 Persistence: Automatic localStorage saving with .persistGlobal() ⚡ Performance: Built on Zustand for optimal re-rendering 🔧 Flexible: Support for any data type (objects, arrays, functions, etc.) 📱 Lightweight: Minimal dependencies, small bundle size 🛡️ Type Safe: Full TypeScript support with autocomplete 🎯 Simple: No providers, reducers, or complex setup required

Perfect For

• Small to Medium Apps: Where Redux might be overkill
• Prototypes: Quick state management setup
• Component Libraries: Easy state sharing between components
• Forms: Persistent form state across page reloads
• Settings: User preferences and app configuration
• Real-time Data: Shared state between multiple components

How It Compares

Import Styles

You can import the hook as either a named or default import:

// Named import (recommended)
import { useReactiveState } from 'reactivestate-a2';

// Default import (also works)
import useReactiveState from 'reactivestate-a2';

Usage Guide: All Features

1. Installation

npm install reactivestate-a2

2. Local State (like useState)

function Counter() {
  const [count, setCount] = useReactiveState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

3. Global State (shared across components)

function InputA() {
  const [value, setValue] = useReactiveState().global('sharedKey');
  return <input value={value} onChange={e => setValue(e.target.value)} />;
}

function DisplayB() {
  const [value] = useReactiveState().global('sharedKey');
  return <div>Shared Value: {value}</div>;
}

4. Persistent Global State (localStorage)

function PersistentInput() {
  const [text, setText] = useReactiveState('').persistGlobal('persistKey');
  return <input value={text} onChange={e => setText(e.target.value)} />;
}

5. API Reference

• useReactiveState(initialValue?)
  • Acts like useState for local state.
  • Chain .global(key) to use global state by key.
  • Chain .persistGlobal(key) to persist the state in localStorage.
  • Use .get(key) for read-only access to global state.
  • Use .set(key) for write-only access to global state.

6. Advanced: Read/Write Only Access

// Read-only global state
const value = useReactiveState().get('sharedKey');

// Write-only global state
const setValue = useReactiveState().set('sharedKey');

7. TypeScript Support

The hook is fully typed, so you get type safety and autocompletion in TypeScript projects.

8. Supported Value Types

You can use any value type with useReactiveState:

• Number: const [n, setN] = useReactiveState(0);
• String: const [s, setS] = useReactiveState('hello');
• Array: const [arr, setArr] = useReactiveState([1, 2, 3]);
• Object: const [obj, setObj] = useReactiveState({ a: 1 });
• Function: const [fn, setFn] = useReactiveState(() => alert('Hi!'))
• Any custom type: Works with anything you can store in state.

Example:

const [number, setNumber] = useReactiveState(42);
const [text, setText] = useReactiveState('hello');
const [list, setList] = useReactiveState([1, 2, 3]);
const [user, setUser] = useReactiveState({ name: 'Alice', age: 30 });
const [callback, setCallback] = useReactiveState(() => alert('Hi!'));

9. Example: All Features Together

import { useReactiveState } from 'reactivestate-a2';

function App() {
  // Local state
  const [local, setLocal] = useReactiveState(0);

  // Global state
  const [global, setGlobal] = useReactiveState().global('myGlobalKey');

  // Persistent global state
  const [persisted, setPersisted] = useReactiveState('').persistGlobal('myPersistedKey');

  return (
    <div>
      <div>
        <h3>Local: {local}</h3>
        <button onClick={() => setLocal(local + 1)}>Inc Local</button>
      </div>
      <div>
        <h3>Global: {global}</h3>
        <button onClick={() => setGlobal(global + 1)}>Inc Global</button>
      </div>
      <div>
        <h3>Persisted: {persisted}</h3>
        <input value={persisted} onChange={e => setPersisted(e.target.value)} />
      </div>
    </div>
  );
}

10. Summary Table

Tip:

• Use unique string keys for each global state to avoid conflicts.
• Use .persistGlobal() only when you want persistence.
• Works with both JavaScript and TypeScript.

Features

• Local and Global State: Use as a drop-in replacement for React's useState, or easily create global state shared across components.
• Global State by Key: Define and access global state using unique string keys, making state sharing explicit and organized.
• Optional Persistence: Enable localStorage persistence for any global state key with a simple API extension.
• TypeScript Support: Fully typed API for safe and predictable usage in TypeScript projects.
• Simple, Clean API: Minimal learning curve—works seamlessly with both JavaScript and TypeScript.
• Conflict Prevention: Prevents duplicate global keys to avoid accidental state overwrites.
• Powered by Zustand: Leverages the performance and flexibility of Zustand under the hood.
• No Boilerplate: No need for reducers, actions, or context providers—just import and use.
• Lightweight: Minimal dependencies and small bundle size.

Installation

`bash npm i reactivestate-a2