Skip to content
kramme:connect-migrate-legacy-store-to-ngrx-component-store logo

kramme:connect-migrate-legacy-store-to-ngrx-component-store

Use this Skill when working in the Connect monorepo and needing to migrate legacy CustomStore or FeatureStore implementations to NgRx ComponentStore.

SKILL.md

Full skill instructions

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.

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View