/web-state-ngrx-signalstore

name: web-state-ngrx-signalstore
description: NgRx SignalStore patterns for Angular state management. Use when managing client state with Angular Signals, composing store features, handling entities, or integrating RxJS effects.

NgRx SignalStore Patterns

> **Quick Guide:** Use NgRx SignalStore for reactive client state in Angular 17+. Compose stores with `withState`, `withComputed`, `withMethods`. Use `patchState` for immutable updates. Use `withEntities` for collections. NEVER use traditional NgRx patterns (actions, reducers, effects) in new SignalStore code.

**Detailed Resources:**

• [examples/core.md](examples/core.md) - signalStore, withState, withComputed, withMethods, withProps
• [examples/entities.md](examples/entities.md) - withEntities, CRUD operations, prependEntity/upsertEntity (v20+)
• [examples/effects.md](examples/effects.md) - rxMethod, signalMethod (v19+), side effects
• [examples/features.md](examples/features.md) - signalStoreFeature, custom features, DevTools
• [examples/testing.md](examples/testing.md) - Unit tests, unprotected(), mocking strategies
• [examples/migration.md](examples/migration.md) - Migration from traditional NgRx
• [reference.md](reference.md) - Decision frameworks, anti-patterns, red flags

---

<critical_requirements>

CRITICAL: Before Managing State with NgRx SignalStore

**(You MUST use `patchState()` for ALL state updates - NEVER mutate state directly)**

**(You MUST wrap async operations in `rxMethod()` from `@ngrx/signals/rxjs-interop` for RxJS integration)**

**(You MUST use `withEntities()` from `@ngrx/signals/entities` for entity collections - NOT arrays in state)**

**(You MUST use named exports ONLY - NO default exports in any store files)**

**(You MUST use named constants for ALL numbers - NO magic numbers in state code)**

</critical_requirements>

---

**Auto-detection:** NgRx SignalStore, signalStore, withState, withComputed, withMethods, patchState, withEntities, rxMethod, signalStoreFeature, @ngrx/signals

**When to use:**

• Managing reactive client state in Angular 17+ applications
• Building composable, reusable store features
• Handling entity collections with CRUD operations
• Integrating RxJS operators for side effects
• Applications requiring fine-grained reactivity with Angular Signals

**Key patterns covered:**

• Store creation with `signalStore()` and `providedIn` options
• State, computed, and methods composition
• Entity management with `withEntities`
• RxJS integration with `rxMethod` and signal-only `signalMethod`
• Custom features with `signalStoreFeature` and context-aware `withFeature` (v20+)
• Derived reactive state with `withLinkedState` (v20+)
• Call state patterns (loading, loaded, error)

**When NOT to use:**

• Server/API data as primary source (use HTTP services with rxMethod for caching)
• Simple component-local state (use Angular signals directly)
• Projects still on Angular < 17 (requires signals)
• Teams unfamiliar with functional composition patterns

---

<philosophy>

Philosophy

NgRx SignalStore is a lightweight, functional state management solution built on Angular Signals. It replaces traditional NgRx patterns (actions, reducers, effects, selectors) with a composable, feature-based approach that eliminates boilerplate while maintaining predictability.

**Core Principles:**

1. **Functional Composition** - Build stores by composing features like `withState`, `withComputed`, `withMethods` 2. **Signal-Based Reactivity** - Leverage Angular's fine-grained reactivity for optimal performance 3. **Immutable Updates** - Use `patchState()` for predictable state transitions 4. **Extensibility** - Create custom features with `signalStoreFeature()` for reuse across stores

**Key Architecture Decisions:**

1. **`signalStore()`** creates a fully typed store as an injectable Angular service 2. **`patchState()`** ensures immutable updates without Immer dependency 3. **`withEntities()`** provides standardized entity management (normalized `ids`/`entityMap` structure with built-in CRUD updaters) 4. **`rxMethod()`** bridges Angular Signals with RxJS for complex async flows 5. **Protected state** (v18+) prevents external mutations by default; v19+ applies deep freeze recursively

**State Ownership:**

| State Type | Solution | Reason | | --------------------- | ------------------------ | ------------------------------------ | | Server/API data | HTTP services + rxMethod | Caching in store, fetch via services | | Shared client state | SignalStore | Reactivity, composition, DevTools | | Component-local state | Angular signals | Simpler, no overhead | | URL state (filters) | Router query params | Shareable, bookmarkable |

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Basic Store with signalStore

Create stores using `signalStore()` with `withState`, `withComputed`, and `withMethods`.

Feature Ordering

Features execute in order. State features must come first:

1. `withState()` - Define state 2. `withComputed()` - Derived values from state 3. `withMethods()` - Actions that update state 4. `withHooks()` - Lifecycle hooks (onInit, onDestroy)

For implementation examples, see [examples/core.md](examples/core.md).

---

Pattern 2: State Updates with patchState

Use `patchState()` for all state modifications. It ensures immutability and proper signal notifications.

When to Use

• Synchronous state updates
• Partial state updates (spread not needed)
• Inside `withMethods()` and custom features

Key Behaviors

• Accepts partial state object or updater functions
• Multiple updaters can be passed to single call
• Works with entity updaters from `@ngrx/signals/entities`

For implementation examples, see [examples/core.md](examples/core.md).

---

Pattern 3: Entity Management with withEntities

Use `withEntities()` for collections of items with