Angular Philosophies

Chapter 03 · State

The signal store

The shape of a store: the facade rule, one store per view, who provides it.

15 rules3 min readSource on GitHub

NgRx SignalStore is the centre of this guide. It gives a page one object with its state, its derived values, its API calls and its actions, built from small features that compose. Everything here targets @ngrx/signals 22.

The rule

A signalStore is the facade, the API layer and the state layer for its slice. It is not a plain service next to a store next to some .subscribe() wiring. From that follow three consequences:

  • Components inject a store and read signals. They never inject HttpClient or a data service.
  • Components never .subscribe(). Anything reactive is a signal, a resource or an rxMethod.
  • Components never call a load() method after a filter changes. Reads are resources derived from state, so changing the filter signal changes the request. See 04-data-access.md.

One store per view

When a feature has a list, a detail page and a form, each page gets its own store:

ts
orders/
  order.model.ts          types and static option lists. No store, no injection
  order.store.ts          feature store: reference data every view needs, providedIn: 'root'
  order-list/
    order-list.store.ts   view store, provided by the component
    order-list.component.ts
    order-list.component.html
  order-form/
    order-form.store.ts   view store, provided by the component
    ...

Do not merge list state and form state because they belong to the same feature. Each view owns its filters, paging, dialog state and its own reads and writes.

StoreProvidedWhy
Feature store (reference data, lookups){ providedIn: 'root' }Stable for the session and shared by every view, so it is fetched once
View store (list, detail, form)providers: [OrderListStore] on the componentFilters, paging and dialog state must reset when the user leaves, not leak into the next visit
Cross-feature state (auth, layout)a library store, providedIn: 'root'Owned by a library, never by one feature

State shared by two features belongs in a library store. A feature must never reach into another feature's store.

The shape of a store

The full file is templates/signal-store/order-list.store.ts. The skeleton:

ts
interface OrderListState {
  page: number;
  search: string;
  status: OrderStatus | null;
}

const initialState: OrderListState = { page: 1, search: '', status: null };

export const OrderListStore = signalStore(
  guardedDevtools('orderList'),
  withState(initialState),
  withProps(...),       // injected services, debounced signals, private helpers
  withResource(...),    // reads
  withMutations(...),   // writes
  withComputed(...),    // derived values
  withMethods(...),     // actions
);

The order is deliberate. Each feature can use what the ones above it added, so state comes first and methods last.

  • Type the state with an interface and name the starting value initialState. A store that outlives its page also exposes reset(), which is patchState(store, initialState).
  • Change state only with patchState. Never mutate an array or an object in place; replace it.
  • Put derived values in withComputed, not in methods and not in the template.
  • Inject with inject() inside withProps, withMethods or withHooks. A store has no constructor.
  • Prefix private members with _. Underscore-prefixed state, props and methods are not exposed on the store instance, so _debouncedSearch and _listReload stay inside the store. Expose a deliberate method (refresh()) when callers need it.
  • Reset the page when a filter changes. Every filter setter patches page: 1 in the same call, because a filter applied on page 5 can leave you past the last page.
  • Never type a store as any. If declaration emit complains in a library, export an interface for the public surface.

Commands that are not plain requests

A search that must not overlap itself, or a command with several steps, is better as an rxMethod:

ts
search: rxMethod<string>(
  pipe(
    tap(() => store.setLoading()),
    exhaustMap(q =>
      http.get<Page<Product>>('/api/products', { params: { q } }).pipe(
        tapResponse({
          next: ({ items }) => patchState(store, { products: items }),
          error: () => store.setError('search-failed'),
        }),
      ),
    ),
  ),
),

Choose the flattening operator on purpose: switchMap for a search where only the latest matters, exhaustMap for a submit that must not run twice, concatMap when order matters. The complete store is product-search.store.ts. It also shows setLoading and setError, which come from the custom feature in 06-custom-features.md.

Reach for rxMethod when you need operators. A request derived from state is a resource, and a plain command is a mutation.

State that survives a reload

Persist with withStorageSync, never with hand-written localStorage.getItem calls. See 05-toolkit.md and layout.store.ts, which persists only the theme and the language and leaves sidebarCollapsed alone.

Testing a store

A store spec injects the store with a fake HttpClient, drives it through its public methods and asserts on its signals. The complete example is order-list.store.spec.ts, and 09-testing.md explains the toolkit it uses. Every store gets a spec.

Rules

These are the lines your AI tool receives. Each one is a sentence on its own.

  1. Make a signalStore the facade, API layer and state layer for its slice; components never inject HttpClient or a data service.
  2. Never call .subscribe() in a component; use signals, resources or rxMethod.
  3. Never add a load() method that a component must call after a filter changes; derive reads from state with resources.
  4. Use one store per view (list, detail, form), provided by the component with providers: [XStore].
  5. Provide a feature store for shared reference data with { providedIn: 'root' }; put cross-feature state in a library store.
  6. Never let a feature import another feature's store.
  7. Type state with an interface, name the starting value initialState, and expose reset() when the store outlives its page.
  8. Change state only with patchState; never mutate arrays or objects in place.
  9. Put derived values in withComputed; inject dependencies with inject() inside withProps, withMethods or withHooks.
  10. Prefix private store members with _ and expose a deliberate method when callers need them.
  11. Reset page to 1 in every filter setter.
  12. Never type a store as any.
  13. Use rxMethod only when operators are needed; choose switchMap, exhaustMap or concatMap deliberately.
  14. Persist state with withStorageSync, never with hand-written localStorage calls.
  15. Give every store a spec.