bodega

bodega is a schema-first component store inspired by ZagJS, powered by TanStack Store and alien-signals. Describe a component's props, state, derived, and actions once — get back one hook that handles context, controllable state, and slice-level subscriptions.

Why it exists

It splits a component's concerns. The schema is the brain — you read the contract first, the implementation second:

interface CounterSchema extends ComponentStoreSchema {
  props: {
    value?: number;
    defaultValue?: number;
    onValueChange?: (next: number) => void;
  };
  state: { count: number };
  derived: { isEven: boolean };
  actions: { increment: () => void; reset: () => void };
}

The brain, up top. An easy-to-read schema is the contract; implementation comes second.
Less boilerplate in the parts. No context wiring, no controlled/uncontrolled branching.
Fine-grained. A part subscribes to one slice and re-renders only when that slice changes.
Practically free. In any repo already on TanStack, this is a near-zero-cost dep.
LLM-friendly. Typesafe conventions a model can follow without inventing its own.

Core concepts

A store is four buckets, resolved in order:

{
  props,    // 1. external inputs, normalized + defaulted once at the boundary
  state,    // 2. reactive cells (a `bindable` cell name matches its controlling prop)
  derived,  // 3. pure projections of state + props
  actions,  // 4. co-located mutations, declared last so they can write any cell
}

One store, two modes — the root owns, the leaves inherit:

const { Provider } = useCounterStore(props);        // boundary: creates + owns the store
const { useSelector } = useCounterStore("inherit"); // leaf: reads the nearest store

A taste of the API

Recommended structure — index says what's public, Root is the only part that initiates the store, store is the brain, the rest are leaves:

counter/
├── index.ts      // barrel — the public menu (re-exports only)
├── store.ts      // the brain
├── Root.tsx      // creates the store, the boundary
├── Value.tsx     // leaf — reads the store
└── Controls.tsx  // leaf — reads the store

store.ts — schema in, hook out. Nothing else leaves the file:

// store.ts
import {
  createComponentStore,
  type ComponentStoreProps,
  type ComponentStoreSchema,
} from "@bodega";
 
interface CounterSchema extends ComponentStoreSchema {
  props: {
    value?: number;
    defaultValue?: number;
    onValueChange?: (next: number) => void;
  };
  state: { count: number };
  derived: { isEven: boolean };
  actions: { increment: () => void; reset: () => void };
}
 
const counterStore = createComponentStore<CounterSchema>({
  name: "Counter",
  props: ({ props }) => ({
    value: props.value,
    defaultValue: props.defaultValue ?? 0,
    onValueChange: props.onValueChange,
  }),
  state: ({ bindable, prop }) => ({
    count: bindable<number>(() => ({
      defaultValue: prop("defaultValue"),
      value: prop("value"),
      onChange: (next) => prop("onValueChange")?.(next),
    })),
  }),
  derived: ({ get }) => ({
    isEven: () => get().count % 2 === 0,
  }),
  actions: ({ get, set }) => ({
    increment: () => set({ count: get().count + 1 }),
    reset: () => set({ count: 0 }),
  }),
});
 
export const useCounterStore = counterStore.useComponentStore;       // parts read the store
export const { splitProps } = counterStore;                          // Root peels store props off the rest
export type CounterStoreProps = ComponentStoreProps<typeof counterStore>;

Leaves inherit and subscribe to just their slice:

// Value.tsx
import { useCounterStore } from "./store";
 
export function Value() {
  const { useSelector } = useCounterStore("inherit");
  const count = useSelector((state) => state.count); // re-renders only when `count` changes
  return <span>{count}</span>;
}

// Controls.tsx
import { useCounterStore } from "./store";
 
export function Controls() {
  const { useActions } = useCounterStore("inherit");
  const { increment, reset } = useActions();
  return (
    <>
      <button onClick={increment}>+</button>
      <button onClick={reset}>Reset</button>
    </>
  );
}

index.ts decides the public surface — two shapes from the same parts.

Flattened — Root composes the leaves itself; the consumer just drops it in. Most common for a component local to one route:

// Root.tsx
import { type CounterStoreProps, useCounterStore } from "./store";
import { Value } from "./Value";
import { Controls } from "./Controls";
 
export function Root(props: CounterStoreProps) {
  const { Provider } = useCounterStore(props); // props are exactly the store's → pass straight through
  return <Provider><Value /><Controls /></Provider>;
}

// index.ts
import { Root } from "./Root";
export const Counter = Root;                    // internal "Root" hidden behind the public name
export { useCounterStore, type CounterStoreProps } from "./store";

// usage
<Counter defaultValue={3} onValueChange={(next) => console.log(next)} />

Compound — leaves are exposed so the consumer arranges them; Root is just the boundary. Most common for a design-system component:

// Root.tsx
import { type CounterStoreProps, splitProps, useCounterStore } from "./store";
 
type RootProps = CounterStoreProps & { children: React.ReactNode };
 
export function Root(props: RootProps) {
  const [storeProps, rest] = splitProps(props, ["value", "defaultValue", "onValueChange"]);
  const { Provider } = useCounterStore(storeProps); // split store props off the children/DOM passthrough
  return <Provider>{rest.children}</Provider>;
}

// index.ts
import { Root } from "./Root";
import { Value } from "./Value";
import { Controls } from "./Controls";
export const Counter = { Root, Value, Controls };
export { useCounterStore, type CounterStoreProps } from "./store";

// usage
<Counter.Root defaultValue={3} onValueChange={(next) => console.log(next)}>
  <Counter.Value />
  <Counter.Controls />
</Counter.Root>