Connect - Migrate Legacy Store to NgRx ComponentStore

Instructions

When to use this skill:

• You're working in the Connect monorepo (

  Connect/ng-app-monolith/

  )
• You need to migrate a legacy

  CustomStore

  or

  FeatureStore

  to modern NgRx ComponentStore
• You see patterns like

  addApiAction().withReducer()

  or

  addSocketAction().withReducer()

• The store uses centralized NgRx Store with feature state slices

Context: Connect's frontend is migrating from a custom store abstraction built on top of NgRx Store to standalone NgRx ComponentStore services. This provides better encapsulation, simpler testing, and eliminates the need for actions/reducers/selectors boilerplate.

Guideline Keywords

• ALWAYS — Mandatory requirement, exceptions are very rare and must be explicitly approved
• NEVER — Strong prohibition, exceptions are very rare and must be explicitly approved
• PREFER — Strong recommendation, exceptions allowed with justification
• CAN — Optional, developer's discretion
• NOTE — Context, rationale, or clarification
• EXAMPLE — Illustrative example

Strictness hierarchy: ALWAYS/NEVER > PREFER > CAN > NOTE/EXAMPLE

---

Migration Checklist

1. Store Structure Transformation

• ALWAYS convert the store to a standalone service class extending

  ComponentStore<StateInterface>

• ALWAYS use

  providedIn: 'root'

  for stores that need application-wide singleton behavior
• ALWAYS define state as interface/type with

  readonly

  properties
• ALWAYS extract

  initialState

  to a constant; use eager initialization in the constructor
• ALWAYS end class names with a

  Store

  suffix
• ALWAYS have file names for Component Stores include

  .store.ts

• PREFER flat state structures to avoid nested objects in state

EXAMPLE - Before (Legacy):

export const eventStore = new FeatureStore('event')
  .addApiAction('loadEvents')
  .withReducer((state, events) => ({ ...state, events }));

EXAMPLE - After (ComponentStore):

interface EventStoreState {
  readonly events: Event[];
  readonly isLoading: boolean;
}

const initialState: EventStoreState = {
  events: [],
  isLoading: false,
};

@Injectable({ providedIn: 'root' })
export class EventStore extends ComponentStore<EventStoreState> {
  constructor() {
    super(initialState);
  }
}

2. State Management Patterns

• ALWAYS replace

  addApiAction().withReducer()

  patterns with ComponentStore updaters and effects
• ALWAYS replace

  addSocketAction().withReducer()

  with updaters that accept observables
• ALWAYS wire websocket observables directly to updaters in the constructor (no manual subscriptions needed)
• ALWAYS use

  tapResponse

  from

  @ngrx/operators

  (not

  @ngrx/component-store

  ) for effect error handling
• NOTE: ComponentStore handles subscriptions automatically

EXAMPLE - Replace API Actions with Effects:

// Legacy: addApiAction().withReducer()
// New: ComponentStore effect
readonly loadEvents = this.effect<void>(
  pipe(
    tap(() => this.setLoading(true)),
    switchMap(() =>
      this.#api.getEvents().pipe(
        tapResponse({
          next: (events) => this.setEvents(events),
          error: (error) => this.#errorHandler.handle(error),
          finalize: () => this.setLoading(false),
        })
      )
    )
  )
);

EXAMPLE - Replace Socket Actions with Updaters:

// Wire websocket observables directly to updaters in constructor
constructor() {
  super(initialState);

  // Subscribe to websocket actions and wire to updaters
  this.addEvent(this.#wsService.action<Event>('AddEvent'));
  this.updateEvent(this.#wsService.action<Event>('UpdateEvent'));
  this.removeEvent(this.#wsService.action<{ id: string }>('RemoveEvent'));

  // Trigger load on websocket connection
  this.loadEvents(
    this.#wsService.connectionState$.pipe(
      filter((state) => state === 'Connected'),
      map(() => undefined)
    )
  );
}

3. Updaters (State Mutations)

• ALWAYS use updaters to change state (not

  setState

  or

  patchState

  )
• ALWAYS use

  set

  prefix for updaters that replace entire state slices
• ALWAYS keep state transformations pure and predictable
• NOTE: Updaters can accept

  PayloadType | Observable<PayloadType>

  - wire observables directly

EXAMPLE:

// Updaters accept PayloadType | Observable<PayloadType>
readonly setEvents = this.updater<Event[]>((state, events) => ({
  ...state,
  events,
}));

readonly addEvent = this.updater<Event>((state, event) => ({
  ...state,
  events: [...state.events, event],
}));

readonly updateEvent = this.updater<Event>((state, updated) => ({
  ...state,
  events: state.events.map((e) => (e.id === updated.id ? updated : e)),
}));

readonly removeEvent = this.updater<{ id: string }>((state, { id }) => ({
  ...state,
  events: state.events.filter((e) => e.id !== id),
}));

readonly setLoading = this.updater<boolean>((state, isLoading) => ({
  ...state,
  isLoading,
}));

4. Selectors (State Reads)

• ALWAYS expose state via selectors, suffix static selectors with

  $

• ALWAYS prefix parameterized selectors with

  select

• NEVER use

  ComponentStore.get()

  — always read via selectors
• ALWAYS do one-off reads in effects by composing with

  withLatestFrom(...)

• ALWAYS compute derived state in selectors (do not store derived state)
• NEVER use

  tap

  /

  tapResponse

  in selectors

EXAMPLE:

// Replace legacy selectors with ComponentStore selectors
readonly events$ = this.select((state) => state.events);
readonly isLoading$ = this.select((state) => state.isLoading);

// Computed/derived state
readonly activeEvents$ = this.select(
  this.events$,
  (events) => events.filter((e) => e.isActive)
);

5. Effects Best Practices

• ALWAYS only use

  tapResponse

  nested in inner pipes (after

  switchMap

  /

  mergeMap

  )
• ALWAYS use the RxJS

  pipe

  operator directly in effects:

  this.effect<Type>(pipe(...))

  instead of

  this.effect<Type>((trigger$) => trigger$.pipe(...))

• ALWAYS use

  switchMap

  for effects that should cancel previous requests
• NEVER subscribe directly to form controls or observables inside components; wire them into store effects
• NEVER provide an empty observable (e.g.,

  this.effectName(of(undefined))

  ) when calling effects without arguments
  • NOTE: The effect creates its own trigger observable internally; use

    this.effectName()

    instead
• ALWAYS import

  tapResponse

  from

  @ngrx/operators

  , not

  @ngrx/component-store

EXAMPLE - Correct import:

import { tapResponse } from '@ngrx/operators';

EXAMPLE - Nested tapResponse pattern:

readonly saveEvent = this.effect<Event>(
  pipe(
    switchMap((event) =>
      this.#api.saveEvent(event).pipe(
        tapResponse({
          next: (saved) => this.updateEvent(saved),
          error: (error) => this.#errorHandler.handle(error),
        })
      )
    )
  )
);

6. Websocket Integration

• ALWAYS inject

  ConnectSharedDataAccessWebsocketService

  in the store, not in a separate service
• ALWAYS wire websocket action observables directly to updaters in the constructor
• ALWAYS wire connection state to load effects using

  filter

  and

  map

• NEVER use

  takeUntilDestroyed

  for root-provided stores
  • NOTE: ComponentStore handles cleanup automatically for root stores

EXAMPLE:

readonly #wsService = inject(ConnectSharedDataAccessWebsocketService);

constructor() {
  super(initialState);

  // Wire websocket actions directly
  this.addItem(this.#wsService.action<Item>('AddItem'));
  this.updateItem(this.#wsService.action<Item>('UpdateItem'));

  // Trigger load on connection
  this.loadItems(
    this.#wsService.connectionState$.pipe(
      filter((state) => state === 'Connected'),
      map(() => undefined)
    )
  );
}

7. Update Consumers

• ALWAYS use the

  inject()

  function instead of constructor injection
• ALWAYS place all

  inject()

  calls first in the class as readonly fields
• ALWAYS use ECMAScript

  #privateField

  syntax for private members
• NEVER use the

  public

  or

  private

  keywords in TypeScript

EXAMPLE - Components Before:

readonly events$ = this.#store.select(eventSelectors.selectEvents);

ngOnInit() {
  this.#store.dispatch(eventActions.loadEvents());
}

EXAMPLE - Components After:

readonly #eventStore = inject(EventStore);
readonly events$ = this.#eventStore.events$;

ngOnInit() {
  this.#eventStore.loadEvents();
}

EXAMPLE - Services Before:

this.#store.dispatch(eventActions.updateEvent({ event }));

EXAMPLE - Services After:

this.#eventStore.saveEvent(event);

8. Clean Up Legacy Code

• ALWAYS remove store registration from feature store config (e.g.,

  provide-event-store.ts

  )
• ALWAYS remove state slice from feature state interface
• ALWAYS remove reducer mappings
• ALWAYS remove legacy action exports (unless maintaining backward compatibility)
• ALWAYS remove legacy selector exports (unless maintaining backward compatibility)
• ALWAYS remove

  Store

  injection from components/services only using this store
• ALWAYS update tests to use ComponentStore directly

---

Critical Rules

Encapsulation

• ALWAYS use subclassed services (not components) for stores
• ALWAYS place the subclassed store in a separate file in the same folder as the component
• ALWAYS use only inherited members inside the store; expose public state via selectors

Lifecycle

• NEVER use lifecycle hooks (

  OnStoreInit

  ,

  OnStateInit

  )
• NEVER use

  provideComponentStore

  ; prefer standard providers

What NOT to Do

• NEVER use

  takeUntilDestroyed

  for root-provided stores
  • NOTE: ComponentStore handles cleanup automatically; only needed for component-scoped stores
• NEVER use

  ComponentStore.get()

  • ALWAYS read state through selectors; use

    withLatestFrom()

    in effects for one-off reads
• NEVER create manual subscriptions
  • ALWAYS wire observables directly to updaters/effects; let ComponentStore manage subscriptions
• NEVER import

  tapResponse

  from

  @ngrx/component-store

  • ALWAYS import from

    @ngrx/operators

    :

    import { tapResponse } from '@ngrx/operators';

• NEVER provide empty observables to effects
  • EXAMPLE: Use

    this.loadEvents()

    not

    this.loadEvents(of(undefined))

• NEVER keep legacy action/selector exports unless explicitly maintaining backward compatibility
• NEVER register ComponentStores in feature store configurations

---

File Organization

• ALWAYS follow the library naming pattern:

  libs/<product>/<application>/<domain>/<type>-<name>

  • NOTE: Product:

    academy

    ,

    coaching

    ,

    connect

    ,

    shared

  • NOTE: Application:

    cms

    ,

    shared

    ,

    ufa

    (User-Facing Application)
  • NOTE: Type:

    data-access

    ,

    feature

    ,

    ui

    , etc.

EXAMPLE:

libs/connect/ufa/events/
├── data-access-event/
│   └── src/
│       ├── lib/
│       │   └── event.store.ts          # New ComponentStore
│       └── index.ts                     # Export store
└── feature-events/
    └── src/
        └── lib/
            └── event-list/
                └── event-list.component.ts  # Inject and use store

---

Testing ComponentStores

• ALWAYS use TestBed to configure the component store and its dependencies
• ALWAYS test selectors by subscribing and verifying emitted values
• ALWAYS test updaters by calling them and verifying state changes via selectors
• ALWAYS test effects by triggering them and verifying side effects
• ALWAYS use

  { provide: Service, useValue: mockService }

  to mock dependencies
• ALWAYS use

  jest.spyOn()

  to verify side effects
• CAN use

  patchState

  with

  // eslint-disable-next-line no-restricted-syntax

  for test setup only
• ALWAYS include the class name in

  describe()

  blocks:

  describe(MyStore.name, () => ...)

• ALWAYS write test descriptions that clearly state expected behavior:

  it('should...')

EXAMPLE:

describe(EventStore.name, () => {
  let store: EventStore;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        EventStore,
        { provide: ApiService, useValue: mockApiService },
      ],
    });
    store = TestBed.inject(EventStore);
  });

  it('should load events', (done) => {
    // Test selectors by subscribing
    store.events$.pipe(skip(1)).subscribe((events) => {
      expect(events).toEqual(mockEvents);
      done();
    });

    // Trigger effect
    store.loadEvents();
  });
});

---

Quick Reference: Member Order

• ALWAYS order members in ComponentStore classes consistently:

1. Injected dependencies (

   inject()

   )
2. Selectors (

   readonly prop$ = this.select(...)

   )
3. Constructor (wire websockets, connection triggers)
4. Effects (

   readonly effectName = this.effect(...)

   )
5. Updaters (

   readonly setX = this.updater(...)

   )
6. Private helpers

---

Additional Best Practices from AGENTS.md

• ALWAYS check AGENTS.md for for the latest definite best practices

TypeScript

• ALWAYS prefer type inference when the type is obvious
• ALWAYS avoid the

  any

  type; use

  unknown

  when type is uncertain
• ALWAYS use ECMAScript

  #privateField

  syntax for encapsulation
• NEVER use the

  public

  or

  private

  keywords in TypeScript class members

Angular Components Using Stores

• ALWAYS set

  changeDetection: ChangeDetectionStrategy.OnPush

  in

  @Component

  decorator
• ALWAYS use separate HTML files (do NOT use inline templates)
• ALWAYS place all

  inject()

  calls first in the class as readonly fields
• ALWAYS place

  @Input

  and

  @Output

  properties second in the class

Templates

• ALWAYS use native control flow (

  @if

  ,

  @for

  ,

  @switch

  ) instead of

  *ngIf

  ,

  *ngFor

  ,

  *ngSwitch

• ALWAYS use the

  *ngrxLet

  directive or

  ngrxPush

  pipe to handle Observables
  • ALWAYS prefer the

    ngrxPush

    pipe over

    async

    for one-off async bindings in templates
  • PREFER not using

    *ngrxLet

    or

    ngrxPush

    multiple times for the same Observable; instead assign it to a template variable using

    @let

Services & Dependency Injection

• ALWAYS use the

  inject()

  function instead of constructor injection
• ALWAYS place all

  inject()

  calls first as private readonly fields
• ALWAYS use the

  providedIn: 'root'

  option for singleton services
• ALWAYS use

  @Component.providers

  for component-level stores

---

Before Submitting Code Review

• ALWAYS ensure all affected tests pass locally
• ALWAYS run formatting:

  yarn run format

  (from

  Connect/ng-app-monolith

  )
• ALWAYS run linting:

  yarn exec nx affected --targets=lint,test --skip-nx-cache

• ALWAYS verify no linting errors are present
• ALWAYS ensure code follows established patterns as outlined in AGENTS.md

Examples

See Instructions Section for code examples.