juststore

A small, expressive, and type-safe state management library for React.

Features

• Type-safe deep state with property-style access (store.user.profile.name)
• Path-based API for dynamic access (store.use("user.profile.name"))
• Fine-grained subscriptions powered by useSyncExternalStore
• Optional persistence + cross-tab sync (createStore)
• Memory-only scoped stores (useMemoryStore, createMemoryStore)
• Built-in form state + validation (useForm, createForm)
• Computed, derived, and mixed read models

Installation

bun add juststore

Quick Start

import { createStore } from "juststore";
import { toast } from "sonner";

type AppState = {
  user: {
    name: string;
    preferences: {
      theme: "light" | "dark";
    };
  };
  todos: { id: number; text: string; done: boolean }[];
};

const store = createStore<AppState>("app", {
  user: {
    name: "Guest",
    preferences: { theme: "light" },
  },
  todos: [],
});

async function initUserDetails() {
  const response = await fetch("/api/user/details");
  const data = (await response.json()) as AppState["user"];
  store.user.set(data);
}

function ThemeToggle() {
  const theme = store.user.preferences.theme.use();
  const nextTheme = theme === "light" ? "dark" : "light";

  const updateTheme = async () => {
    try {
      const response = await fetch("/api/user/preferences/theme", {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ theme: nextTheme }),
      });

      if (!response.ok) {
        throw new Error("Theme update failed");
      }

      store.user.preferences.theme.set(nextTheme);
    } catch {
      toast.error("Failed to update theme");
    }
  };

  return <button onClick={updateTheme}>Theme: {theme}</button>;
}

Real-World Patterns

1) Debounced search + category filter

type SearchState = {
  query: string;
  category: "all" | "running" | "stopped";
  services: { id: string; name: string; status: "running" | "stopped" }[];
};

const searchStore = createStore<SearchState>("services-search", {
  query: "",
  category: "all",
  services: [],
});

function SearchQueryInput() {
  const query = searchStore.query.use() ?? "";
  return (
    <input
      value={query}
      onChange={(e) => searchStore.query.set(e.target.value)}
      placeholder="Search services"
    />
  );
}

function SearchCategoryFilter() {
  const category = searchStore.category.use();
  return (
    <select
      value={category}
      onChange={(e) =>
        searchStore.category.set(e.target.value as SearchState["category"])
      }
    >
      <option value="all">All</option>
      <option value="running">Running</option>
      <option value="stopped">Stopped</option>
    </select>
  );
}

function SearchResults() {
  const query = searchStore.query.useDebounce(150) ?? "";
  const category = searchStore.category.use();

  const visible = searchStore.services.useCompute(
    (services) => {
      const list = services ?? [];
      return list.filter((service) => {
        const nameMatch = service.name
          .toLowerCase()
          .includes(query.toLowerCase());
        const categoryMatch =
          category === "all" ? true : service.status === category;
        return nameMatch && categoryMatch;
      });
    },
    [query, category],
  );

  return (
    <ul>
      {visible.map((service) => (
        <li key={service.id}>{service.name}</li>
      ))}
    </ul>
  );
}

function ServiceSearchPage() {
  return (
    <>
      <SearchQueryInput />
      <SearchCategoryFilter />
      <SearchResults />
    </>
  );
}

2) WebSocket ingestion into normalized state

type RouteUptime = { alias: string; uptime: number };
type UptimeState = {
  routeKeys: string[];
  uptimeByAlias: Record<string, RouteUptime>;
};

const uptimeStore = createStore<UptimeState>("uptime", {
  routeKeys: [],
  uptimeByAlias: {},
});

function onUptimeMessage(rows: RouteUptime[]) {
  const keys = rows.map((row) => row.alias).toSorted();
  uptimeStore.routeKeys.set(keys);

  uptimeStore.uptimeByAlias.set(
    rows.reduce<Record<string, RouteUptime>>((acc, row) => {
      acc[row.alias] = row;
      return acc;
    }, {}),
  );
}

// fine grained subscription
function UptimeComponent({ alias }: { alias: string }) {
  const uptime = uptimeStore.uptimeByAlias[alias]?.uptime.use();
  return <div>Uptime: {uptime ?? "Unknown"}</div>;
}

3) Dynamic object keys for editable maps

type HeaderState = {
  headers: Record<string, string>;
};

const headerStore = createStore<HeaderState>("route-headers", {
  headers: {},
});

function HeadersEditor() {
  // keys is a virtual property that returns a state proxy for the keys array
  // it only recomputes when the keys array changes
  const keys = headerStore.headers.keys.use();

  return (
    <div>
      {keys.map((key) => (
        <div key={key}>
          <input
            value={key}
            onChange={(e) =>
              headerStore.headers.rename(key, e.target.value.trim())
            }
          />
          {/* Render and update without cascade rerendering the entire HeadersEditor */}
          <RenderWithUpdate state={headerStore.headers[key]}>
            {(value, update) => (
              <input value={value} onChange={(e) => update(e.target.value)} />
            )}
          </RenderWithUpdate>
          <button onClick={() => headerStore.headers[key].reset()}>
            remove
          </button>
        </div>
      ))}
    </div>
  );
}

4) Typed form with validation and submit gating

import { useForm } from "juststore";
import {
  StoreFormInputField,
  StoreFormPasswordField,
} from "@/components/store/Input"; // from juststore-shadcn

type LoginForm = {
  email: string;
  password: string;
};

function LoginPage() {
  const form = useForm<LoginForm>(
    { email: "", password: "" },
    {
      email: { validate: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
      password: {
        validate: (value) =>
          value && value.length < 8 ? "Password too short" : undefined,
      },
    },
  );

  return (
    <form onSubmit={form.handleSubmit((values) => console.log(values))}>
      <StoreFormInputField
        state={form.email}
        type="email"
        title="Email"
        placeholder="you@example.com"
      />
      <StoreFormPasswordField
        state={form.password}
        title="Password"
        placeholder="At least 8 characters"
      />
      <button type="submit">Sign in</button>
    </form>
  );
}

5) Mixed read model for unified UI flags

import { createMixedState, createStore } from "juststore";

type OpsState = {
  syncingConfig: boolean;
  savingRoute: boolean;
  reloadingAgent: boolean;
};

const opsStore = createStore<OpsState>("ops", {
  syncingConfig: false,
  savingRoute: false,
  reloadingAgent: false,
});

const busyState = createMixedState(
  opsStore.syncingConfig,
  opsStore.savingRoute,
  opsStore.reloadingAgent,
);

function GlobalBusyOverlay() {
  const isBusy = busyState.useCompute(
    ([syncingConfig, savingRoute, reloadingAgent]) =>
      syncingConfig || savingRoute || reloadingAgent,
  );

  if (!isBusy) return null;
  return <div className="overlay">Loading...</div>;
}

function BusyLabel() {
  const label = busyState.useCompute(
    ([syncingConfig, savingRoute, reloadingAgent]) => {
      if (syncingConfig) return "Syncing config...";
      if (savingRoute) return "Saving route...";
      if (reloadingAgent) return "Reloading agent...";
      return "Idle";
    },
  );

  return <span>{label}</span>;
}

Core Usage

Read and write state

const name = store.user.name.use(); // subscribe
const current = store.user.name.value; // read without subscribe
store.user.name.set("Alice");
store.user.name.set((prev) => prev.toUpperCase());

Path-based dynamic API

store.set("user.name", "Alice");
const name = store.use("user.name");
const value = store.value("user.name");

Arrays

store.todos.push({ id: Date.now(), text: "new", done: false });
store.todos.at(0).done.set(true);
store.todos.sortedInsert((a, b) => a.id - b.id, {
  id: 2,
  text: "x",
  done: false,
});

const len = store.todos.length;
const liveLen = store.todos.useLength();

Computed and derived values

const total = store.cart.items.useCompute(
  (items) => items?.reduce((sum, item) => sum + item.price * item.qty, 0) ?? 0,
);

const fahrenheit = store.temperature.derived({
  from: (celsius) => ((celsius ?? 0) * 9) / 5 + 32,
  to: (f) => ((f - 32) * 5) / 9,
});

Render helpers

import { Conditional, Render, RenderWithUpdate } from "juststore";

<Render state={store.counter}>{(value) => <span>{value}</span>}</Render>;

<RenderWithUpdate state={store.counter}>
  {(value, update) => (
    <button onClick={() => update((value ?? 0) + 1)}>{value}</button>
  )}
</RenderWithUpdate>;

<Conditional state={store.user.role} on={(role) => role === "admin"}>
  <AdminPage />
</Conditional>;

API Reference

Top-Level Exports

• createStore(namespace, defaultValue, options?)
• createMemoryStore(namespace, defaultValue)
• useMemoryStore(defaultValue)
• createForm(namespace, defaultValue, fieldConfigs?)
• useForm(defaultValue, fieldConfigs?)
• createMixedState(...states)
• createAtom(id, defaultValue, persistent?)
• Render, RenderWithUpdate, Conditional, ConditionalRender
• isEqual
• All public types from path, types, and form

createStore(namespace, defaultValue, options?)

Creates a persistent store (unless options.memoryOnly is true).

• namespace: string - storage namespace
• defaultValue: T - default root value
• options?: { memoryOnly?: boolean }

Returns a store that supports both:

• deep proxy usage (store.user.name.use())
• path-based usage (store.use("user.name"))

createMemoryStore(namespace, defaultValue) / useMemoryStore(defaultValue)

Creates memory-only stores (no localStorage persistence).

• createMemoryStore is useful outside React hooks or for explicit namespaces
• useMemoryStore creates component-scoped state keyed by useId()

createAtom(id, defaultValue, persistent?)

Creates a scalar atom-like state.

• persistent defaults to false
• methods: .value, .use(), .set(value | updater), .reset(), .subscribe(listener), .useCompute(fn, deps?)

createForm(namespace, defaultValue, fieldConfigs?) / useForm(defaultValue, fieldConfigs?)

Creates a form store with built-in error state and validation.

Field validators support:

• "not-empty"
• RegExp
• (value, form) => string | undefined

Additional form methods:

• .useError()
• .error
• .setError(message | undefined)
• .clearErrors()
• .handleSubmit(onSubmit)

createMixedState(...states)

Combines multiple states into one read-only tuple-like state.

• .value returns current tuple
• .use() subscribes to all source states
• .useCompute(fn) computes derived values from the tuple

Render utilities

• Render - render-prop helper for read-only usage
• RenderWithUpdate - render-prop helper with updater callback
• Conditional - show/hide children based on predicate; uses Activity so children stay mounted when hidden (state preserved)
• ConditionalRender - render only when predicate is true; children are a render prop receiving the value; returns null when false (unmounted)

Store / State Methods

Root store methods

Method	Description
.state(path)	Returns a state proxy for the path
.use(path)	Subscribes and returns current value
.useDebounce(path, delay)	Debounced subscription
.useState(path)	[value, setValue] convenience tuple
.value(path)	Reads current value without subscription
.set(path, value, skipUpdate?)	Sets value (or updater function)
.reset(path)	Resets path back to default value for that path
.rename(path, oldKey, newKey)	Renames an object key
.subscribe(path, listener)	Subscribes to path updates
.useCompute(path, fn, deps?)	Computes memoized derived values
.notify(path)	Forces listener notification for path

Common state-node methods

Available on all nodes (store.a.b.c):

Method	Description
.value	Read value without subscribing
.field	Last path segment
.use()	Subscribe and read
.useDebounce(delay)	Debounced subscribe/read
.useState()	[value, setValue]
.set(value, skipUpdate?)	Set value (or updater function)
.reset()	Reset path to default value
.subscribe(listener)	Subscribe to path changes
.useCompute(fn, deps?)	Compute derived value
.derived({ from, to })	Bidirectional virtual transform
.ensureArray()	Array-safe state wrapper
.ensureObject()	Object-safe state wrapper
.withDefault(defaultValue)	Fallback for nullish values
.notify()	Forces listener notification

Object-state additions

Method	Description
.keys	Read-only stable keys state
.rename(oldKey, newKey)	Rename object key
[key]	Nested field access

Array-state additions

Method	Description
.length	Current length
.useLength()	Subscribe to length only
.at(index) / [index]	Access item state
.push(...items)	Push items
.pop()	Pop item
.shift()	Shift item
.unshift(...items)	Unshift items
.splice(start, deleteCount?, ...items)	Splice items
.reverse()	Reverse array
.sort(compareFn?)	Sort array
.fill(value, start?, end?)	Fill array
.copyWithin(target, start, end?)	Copy within array
.sortedInsert(cmp, ...items)	Insert by comparator

Notes

• createStore persists by default; use memoryOnly for ephemeral data.
• reset restores default path value passed to createStore, it does not delete to undefined.

License

AGPL-3.0