react

@quantajs/react

React bindings for @quantajs/core. Built on useSyncExternalStore; works with React 18 and 19, StrictMode, SSR and the Next.js App Router.

Documentation · Example app · Changelog

Install

npm install @quantajs/core @quantajs/react

Usage

// stores/todos.ts
import { defineStore } from '@quantajs/core';

export const useTodoStore = defineStore('todos', {
    state: () => ({ items: [] as { text: string; done: boolean }[] }),
    getters: {
        remaining: (s) => s.items.filter((t) => !t.done).length,
    },
    actions: {
        add(text: string) {
            this.items.push({ text, done: false });
        },
    },
});

// Todos.tsx
import { useQuanta, useQuantaActions, useQuantaValue } from '@quantajs/react';
import { useTodoStore } from './stores/todos';

// Re-renders only when `remaining` changes.
export function Remaining() {
    const remaining = useQuantaValue(useTodoStore, (s) => s.remaining);
    return <p>{remaining} left</p>;
}

// Never re-renders on store changes.
export function AddButton() {
    const todos = useQuantaActions(useTodoStore);
    return <button onClick={() => todos.add('New todo')}>Add</button>;
}

// Re-renders on any change to the store.
export function List() {
    const todos = useQuanta(useTodoStore);
    return (
        <ul>
            {todos.items.map((t, i) => (
                <li key={i}>{t.text}</li>
            ))}
        </ul>
    );
}

No provider is needed in a client-only app. Stores resolve against the nearest <QuantaProvider>'s container, or the ambient one.

Hooks

Hook	Subscribes to	Use for
useQuantaValue(definition, selector, options?)	What the selector reads	Most components
useQuanta(definition)	The whole store	Small stores, or components that read most of it
useQuantaActions(definition)	Nothing	Components that only call actions
useLocalStore(definition)	The whole store	A store instance owned by one component, disposed on unmount
useComputed(store, fn, options?)	What fn reads	A cached derivation scoped to a component
useWatch(store, source, callback, options?)	What source reads	Side effects on change

Selectors run on render and whenever state they read changes, so keep them cheap. Define an expensive selector outside the component (or wrap it in useCallback), or use useComputed for a cached derivation.

useQuantaStore(store) and useQuantaSelector(store, selector) are the same as useQuanta and useQuantaValue but take a resolved store instead of a definition.

A selector that builds a new object or array on every call should pass shallow so unchanged projections do not re-render:

import { shallow, useQuantaValue } from '@quantajs/react';
import { useTodoStore } from './stores/todos';

export function Summary() {
    const { remaining, total } = useQuantaValue(
        useTodoStore,
        (s) => ({ remaining: s.remaining, total: s.items.length }),
        { equalityFn: shallow },
    );
    return (
        <p>
            {remaining} of {total} left
        </p>
    );
}

Async action state

import { defineStore } from '@quantajs/core';
import { useQuantaActions, useQuantaValue } from '@quantajs/react';

const useProfile = defineStore('profile', {
    state: () => ({ name: '' }),
    actions: {
        async load() {
            const res = await fetch('/api/me', { signal: this.$signal });
            this.name = (await res.json()).name;
        },
    },
});

export function Profile() {
    const profile = useQuantaActions(useProfile);
    const pending = useQuantaValue(useProfile, (s) => s.load.pending);
    const error = useQuantaValue(useProfile, (s) => s.load.error);

    if (pending)
        return <button onClick={() => profile.load.abort()}>Cancel</button>;
    return (
        <>
            <button onClick={() => profile.load().catch(() => {})}>Load</button>
            {error && <p>{error.message}</p>}
        </>
    );
}

Server rendering

<QuantaProvider> takes an optional container and an optional snapshot from container.dehydrate(). The snapshot is applied before the first render, so the client's markup matches the server's.

'use client';

import type { ReactNode } from 'react';
import type { ContainerSnapshot } from '@quantajs/core';
import { QuantaProvider } from '@quantajs/react';

export function Providers(props: {
    snapshot: ContainerSnapshot;
    children: ReactNode;
}) {
    return (
        <QuantaProvider snapshot={props.snapshot}>
            {props.children}
        </QuantaProvider>
    );
}

On the server, create a container per request, resolve stores against it, and pass its snapshot down. Never resolve a store against the ambient container on the server: it is shared across requests. See the Next.js guide and examples/nextjs-app.

DevTools

npm install -D @quantajs/devtools

import { QuantaDevTools } from '@quantajs/react/devtools';

export function DevPanel() {
    return <QuantaDevTools redact={['token']} />;
}

The panel is loaded lazily and mounts only in development builds unless visible is set. @quantajs/react itself never imports @quantajs/devtools.

License

MIT