Introduction to QuantaJS

Imagine a world where state management in JavaScript feels like a breeze — intuitive, lightweight, and endlessly scalable. Welcome to QuantaJS, the state management library that's here to transform how you build applications. Whether you're crafting a quick prototype or architecting a sprawling enterprise app, QuantaJS delivers a reactivity system so elegant, you'll wonder how you ever lived without it.

The Story Behind QuantaJS

QuantaJS was born from a simple yet powerful realization: the reactivity system that makes Vue.js and Pinia so delightful shouldn't be confined to just the Vue ecosystem. We wanted to bring that same intuitive, performant state management experience to the broader JavaScript world.

If you've ever worked with Pinia, you'll immediately feel at home with QuantaJS. The familiar patterns — stores with state, getters, and actions — are all there, but now they work anywhere JavaScript runs. Whether you're building a React app, a vanilla JavaScript project, or exploring other frameworks, you can enjoy the same reactive magic that makes Vue development so enjoyable.

The goal was simple: take the best parts of modern state management (reactive state, computed values, automatic dependency tracking) and make them accessible to everyone, regardless of their framework choice. We started with React integration because it's where many developers spend their time, but the vision extends far beyond that.

Why QuantaJS Will Steal Your Heart

• Freedom Unleashed: Works anywhere JavaScript does — vanilla, React, Vue, or beyond. No framework? No problem.
• Reactivity Redefined: Say goodbye to clunky boilerplate. Changes are tracked automatically, from simple counters to deeply nested objects, arrays, Maps and Sets. No reassignment tricks required.
• Typed Without the Ceremony: State, getters and actions are inferred end to end. You never restate a generic, and this inside an action is the whole store, fully typed.
• Server-Safe by Construction: Containers give you per-request isolation, so one user's state cannot leak into another's — plus dehydrate() / hydrate() for SSR.
• Async, Batteries Included: Every action carries pending, error and abort(). No hand-rolled loading flags.
• Scales Like a Dream: Tiny scripts or massive systems — QuantaJS grows with you, never weighing you down.
• React Optimized: Hooks built on useSyncExternalStore, fine-grained selectors, and a 2.8 kB gzipped bundle.
• DevTools, Opt-In: Real-time store inspection, action logging and persistence management — attached only when you ask for it.

QuantaJS combines simplicity with power, offering a lightweight alternative to traditional state management libraries. Whether you're building a small prototype or a large-scale app, QuantaJS adapts to your needs without unnecessary complexity.

Package Architecture

QuantaJS is designed as a modular ecosystem of focused packages, so you install only what you need:

@quantajs/core

The framework-agnostic reactivity engine. Stores, containers, reactive state, computed values, watchers, effects, SSR hydration and persistence — everything needed for state management in any JavaScript environment. Ships real ESM and CJS.

import { defineStore, createContainer, reactive, computed, watch } from '@quantajs/core';

@quantajs/react

React bindings built on useSyncExternalStore for concurrent-safe, automatic re-renders — 7.3 kB raw / 2.8 kB gzipped. Provides useQuanta, useQuantaValue, useQuantaActions, useLocalStore, useWatch, useComputed and the QuantaProvider component.

import { useQuanta, useQuantaValue, QuantaProvider } from '@quantajs/react';

@quantajs/devtools

A framework-agnostic developer overlay (built with Preact + Shadow DOM) for real-time store inspection, action history, and persistence debugging.

import { mountDevTools } from '@quantajs/devtools';

What Makes QuantaJS Different

QuantaJS isn't just another library — it's a rebellion against bloated, overcomplicated state management. Born from a desire to simplify without sacrificing power, it's your companion for building smarter, faster, and cleaner code. The modular package architecture means you get exactly what you need — core functionality for any environment, React-specific features when building React applications, and powerful DevTools for debugging and development.

A Taste of the Magic

Here's a sneak peek at what QuantaJS can do:

Core Usage

import { defineStore } from '@quantajs/core';

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

const counter = useCounterStore();
counter.increment();        // Boom! State updates, reactivity kicks in.
console.log(counter.count);   // 1
console.log(counter.doubled); // 2 — cached, recomputed only when `count` changes.

defineStore returns an accessor, not an instance. That is what lets the same file be imported safely on a server, and what gives you full type inference without restating a single generic.

React Integration

import { useQuanta } from '@quantajs/react';
import { useCounterStore } from './stores/counter';

function Counter() {
  const counter = useQuanta(useCounterStore);
  return (
    <div>
      <p>Count: {counter.count}</p>
      <button onClick={() => counter.increment()}>Increment</button>
    </div>
  );
}

No provider required in a client-only app. Add <QuantaProvider> when you need to control the container's lifetime — mostly under SSR.

Async, Without Boilerplate

export const useUsersStore = defineStore('users', {
  state: () => ({ list: [] }),
  actions: {
    async load() {
      const res = await fetch('/api/users', { signal: this.$signal });
      this.list = await res.json();
    },
  },
});

const users = useQuanta(useUsersStore);

<button disabled={users.load.pending}>
  {users.load.pending ? 'Loading…' : 'Load'}
</button>
{users.load.error && <p>{users.load.error.message}</p>}

No isLoading, no error field, no finally you can forget to write.

Get Started

Ready to dive in? Check out the Installation guide or explore the Quick Start to see QuantaJS in action!

Already on 2.0.0? Migrating to 2.1 covers everything that changed.

Support

If you like QuantaJS, give it a ⭐ on GitHub or contribute by submitting issues and pull requests!