# Create Store \[Normalized reactive state in a client-only app]
The store path is rxfy with no server: typed models, normalized entities, and reactive
subscriptions in a plain React app. The idea in one paragraph: rxfy stores each entity
**once**, in a shared store keyed by its id. A query holds only ids and resolves entities
from the store, so when you write an entity — from a refetch, a mutation, or a websocket
push — every component that is subscribed to this entity updates automatically.
## Install
Install the two rxfy packages plus the `rxjs`/`zod`/`lodash` peers:
:::code-group
```bash [npm]
npm install rxfy rxfy-react
npm install rxjs zod lodash
```
```bash [pnpm]
pnpm add rxfy rxfy-react
pnpm add rxjs zod lodash
```
```bash [yarn]
yarn add rxfy rxfy-react
yarn add rxjs zod lodash
```
```bash [bun]
bun add rxfy rxfy-react
bun add rxjs zod lodash
```
:::
rxfy declares `rxjs ^7`, `zod ^4`, and `lodash ^4` as **peer dependencies** so your whole
app shares one copy of each; npm does not install them for you, hence the second line.
`rxfy-react` also needs `react`/`react-dom` 18+, which your React app already has.
## Wrap your app
`StoreProvider` creates the model registry that `useStateData` and `useModelStore`
write to and read from. Wrap your root once:
```tsx [main.tsx]
import { StoreProvider } from "rxfy-react";
import { createRoot } from "react-dom/client";
import { App } from "./App";
createRoot(document.getElementById("root")!).render(
,
);
```
A client-only app passes no props. The SSR props (`ssr`, `registry`, `dehydratedState`)
are covered in [Server-Side Rendering](/core-concepts/ssr).
## Fetch, render, update
One file: a model, a state, a fetch, and two components.
```tsx [App.tsx]
import { z } from "zod";
import { array, asKey, createModel, defineState } from "rxfy";
import { Pending, useAtom, useModelStore, useStateData } from "rxfy-react";
// A model: an entity type plus how to read its id.
const UserModel = createModel({
schema: z.object({ id: z.string(), name: z.string() }),
getKey: (user) => user.id,
name: "user",
});
// A state: what one query fetches — here, a list of users.
const usersState = defineState({
key: "users",
params: z.object({}),
model: { users: array(UserModel) },
});
// Stands in for a real API call; the signature stays the same when you swap it.
async function fetchUsers() {
return {
users: [
{ id: "1", name: "Ada Lovelace" },
{ id: "2", name: "Grace Hopper" },
],
};
}
// Each row subscribes to its own entity by id and re-renders only when that entity changes.
function UserRow({ id }: { id: string }) {
const store = useModelStore(UserModel);
// `id` here is a plain string prop, so brand it with `asKey`. (Type the prop as
// `StoreKey` instead and the query-shape id flows in with no `asKey`.)
const [user] = useAtom(store.get(asKey(UserModel, id)));
return
)}
);
}
```
Run it. You see two names; click **Rename Ada** and the first row changes.
What happened, in order:
1. `useStateData` ran `fetchUsers` and **normalizes** the result: each user was written
into the shared `UserModel` store under its id, and `data$` emitted the query shape —
`{ users: ["1", "2"] }`. It holds ids, not user objects so you can then reference this entity right from the store by its id.
2. Each `UserRow` resolved its own entity with `store.get(id)` — a synchronous, writable
handle. Its id came out of the fulfilled query, so the entity is already in the store;
there is nothing to wait for.
3. The button called `store.set` with a new entity for id `"1"`. The row subscribed to
that id re-rendered; the list and the other row did not, and nothing re-fetched.
Step 3 is the point of the library. A refetch, a mutation, and a websocket message all
land the same way — one write to the store, and every view of that entity updates with no extra (declarative) friction.
Notice what unwraps where. The button sits **outside** `Pending`: a write needs no
unwrapped data, so it never waits on the query. `App` unwraps only the id list; each
`UserRow` reads its one entity synchronously. rxfy keeps values wrapped until the leaf
that renders them — unwrap late, and both loading UI and re-renders stay exactly where
the data is used.
:::tip
`params` compares by value, so passing a fresh `{}` each render is fine. What you fetch is
declared by the state's `params` schema; give it real fields and `useStateData` re-fetches
whenever their values change.
:::
## Writes as mutations
`store.set` is the low-level write. For app-level changes you usually declare **mutations** on
the state instead: named reducers that take the whole fetched shape and return the next one.
rxfy re-normalizes the result back into the store, so every subscribed view updates exactly the
way the `store.set` button did — you describe the change, not the bookkeeping.
Give `usersState` a `mutations` block:
```ts [App.tsx]
const usersState = defineState({
key: "users",
params: z.object({}),
model: { users: array(UserModel) },
mutations: {
addUser: (prev, name: string) => ({
users: [...prev.users, { id: crypto.randomUUID(), name }],
}),
rename: (prev, next: User) => ({
users: prev.users.map((u) => (u.id === next.id ? next : u)),
}),
},
});
type User = z.infer;
```
`useStateData` returns those mutations alongside `data$`; call them from anywhere in the tree:
```tsx [App.tsx]
const { data$, mutations } = useStateData({ state: usersState, fetchFn: fetchUsers, params: {} });
// ...somewhere in the render:
;
```
Reducers work with whole entities, not ids; normalizing the result back into the store is rxfy's
job. A mutation and a websocket push land identically — one write, and every view of that entity
re-renders with no re-fetch.
## Local drafts with Atom and Lens
A form wants a draft the user can type into — and discard — without touching the shared store
until they commit. Hold that draft in a local [`Atom`](/rxfy/create-atom), focus the one field
you're editing with a [`Lens`](/rxfy/create-lens), and bind it with
[`useAtom`](/react/use-atom). The form never reads or writes the store; on submit it hands the
edited entity to `onSave`, and the parent runs the write:
```tsx [EditName.tsx]
import { useMemo } from "react";
import { createAtom, createLens, keyLens } from "rxfy";
import { useAtom } from "rxfy-react";
type User = { id: string; name: string };
export function EditName({ user, onSave }: { user: User; onSave: (user: User) => void }) {
const draft$ = useMemo(() => createAtom(user), [user]);
const name$ = useMemo(() => createLens(draft$, keyLens("name")), [draft$]);
const [name, setName] = useAtom(name$);
return (
);
}
```
`draft$` is a plain `Atom` local to this component; `name$` is a `Lens` onto its `name`
field, and `useAtom` binds that field to the input. Typing updates the draft, not the store; the
row keeps showing the saved name until you submit. Wire `onSave` to the `rename` mutation and the
edit reaches every view of that user at once. `onSave` is your write boundary — against a real
backend it's where you'd `await` a `PATCH` before (or after) the store write.
## Next: Add SSR
Your store works on the client. The next level is
[Add SSR](/getting-started/add-ssr) — render the first paint on the server and hydrate it
with no refetch. Same models, same components; no server push yet.