Forem: Marko Stanimirović

Announcing Events Plugin for NgRx SignalStore: A Modern Take on Flux Architecture

Marko Stanimirović — Mon, 12 May 2025 18:33:31 +0000

We are pleased to announce the introduction of the Events plugin for NgRx SignalStore, released as part of NgRx v19.2! This new addition brings the power of event-based state management to SignalStore, enabling developers to create scalable applications more effectively.

Experimental Stage 🚧

The Events plugin is currently marked as experimental. This means its APIs are subject to change, and modifications may occur in future versions without standard breaking change announcements until it is deemed stable. We encourage you to try it out, provide feedback, and help shape its future!

Flux Architecture 🔄

This plugin takes inspiration from the original Flux architecture and incorporates the best practices and patterns from NgRx Store, NgRx Effects, and RxJS.

The application architecture with the Events plugin is composed of the following building blocks:

Event: Describes an occurrence within the system. Events are dispatched to trigger state changes and/or side effects.
Dispatcher: An event bus that forwards events to their corresponding handlers in the stores.
Store: Contains reducers and effects that manage state and handle side effects, maintaining a clean and predictable application flow.
View: Reflects state changes and dispatches new events, enabling continuous interaction between the user interface and the underlying system.

By dispatching events and reacting to them, the what (the event that occurred) is decoupled from the how (the state changes or side effects that result), leading to predictable data flow and more maintainable code.

Walkthrough 🛠️

The Events plugin provides a set of APIs for defining and handling events in a reactive and declarative manner. The following example demonstrates how these APIs can be used to implement state and behavior orchestration through events.

Defining Events

Events are created using the eventGroup function, which organizes related events under a common source. This function accepts an object with two properties:

source: identifies the origin of the event group (e.g., 'Users Page', 'Users API').
events: a dictionary of named event creators, where each key defines the event name and each value defines the payload type using the type helper from the core @ngrx/signals package.

import { type } from '@ngrx/signals';
import { eventGroup } from '@ngrx/signals/events';

export const usersPageEvents = eventGroup({
  source: 'Users Page',
  events: {
    opened: type<void>(),
    refreshed: type<void>(),
  },
});

export const usersApiEvents = eventGroup({
  source: 'Users API',
  events: {
    loadedSuccess: type<User[]>(),
    loadedFailure: type<string>(),
  },
});

Performing State Changes

To handle state changes in response to events, SignalStore provides the withReducer feature. Case reducers are defined using the on function, which maps one or more events to a case reducer function. Each case reducer receives the event and returns the state update. It supports three forms of return values: a partial state object, a partial state updater, and an array of partial state objects and/or updaters.

import { signalStore } from '@ngrx/signals';
import { setAllEntities, withEntities } from '@ngrx/signals/entities';
import { on, withReducer } from '@ngrx/signals/events';

export const UsersStore = signalStore(
  { providedIn: 'root' },
  withEntities<User>(),
  withRequestStatus(),
  withReducer(
    on(usersPageEvents.opened, usersPageEvents.refreshed, setPending),
    on(usersApiEvents.loadedSuccess, ({ payload }) => [
      setAllEntities(payload),
      setFulfilled(),
    ]),
    on(usersApiEvents.loadedFailure, ({ payload }) => setError(payload)),
  ),
);

💡 Implementation of the withRequestStatus feature and its state updaters is available in the official SignalStore documentation.

Performing Side Effects

Side effects are handled using the withEffects feature. This feature accepts a function that receives the store instance as an argument and returns a dictionary of effects. Each effect is defined as an observable that reacts to specific events using the Events service. If an effect emits a new event, that event will be automatically dispatched.

import { Events, withEffects } from '@ngrx/signals/events';
import { mapResponse } from '@ngrx/operators';

export const UsersStore = signalStore(
  /* ... */
  withEffects(
    (
      store,
      events = inject(Events),
      usersService = inject(UsersService),
    ) => ({
      loadUsers$: events
        .on(usersPageEvents.opened, usersPageEvents.refreshed)
        .pipe(
          exhaustMap(() =>
            usersService.getAll().pipe(
              mapResponse({
                next: (users) => usersApiEvents.loadedSuccess(users),
                error: (error: { message: string }) =>
                  usersApiEvents.loadedFailure(error.message),
              }),
            ),
          ),
        ),
      logError$: events
        .on(usersApiEvents.loadedFailure)
        .pipe(tap(({ payload }) => console.log(payload))),
    }),
  ),
);

Reading State

The plugin doesn’t change how the state is exposed or consumed. Therefore, components can access state and computed signals by using the store instance.

@Component({
  selector: 'app-users',
  template: `
    <h1>Users</h1>

    @if (usersStore.isPending()) {
      <p>Loading...</p>
    }

    <ul>
      @for (user of usersStore.entities(); track user.id) {
        <li>{{ user.name }}</li>
      }
    </ul>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UsersComponent {
  readonly usersStore = inject(UsersStore);
}

Dispatching Events

To initiate state changes or side effects, events can be dispatched using the Dispatcher service. It provides a dispatch method that takes an event as input.

import { Dispatcher } from '@ngrx/signals/events';

@Component({
  /* ... */
  template: `
    <h1>Users</h1>

    <button (click)="refresh()">Refresh</button>
  `,
})
export class UsersComponent {
  readonly usersStore = inject(UsersStore);
  readonly dispatcher = inject(Dispatcher);

  constructor() {
    this.dispatcher.dispatch(usersPageEvents.opened());
  }

  refresh(): void {
    this.dispatcher.dispatch(usersPageEvents.refreshed());
  }
}

For convenience, self-dispatching events can be generated using the injectDispatch function, which returns an object with methods matching the provided event creators.

import { injectDispatch } from '@ngrx/signals/events';

@Component({
  /* ... */
  template: `
    <h1>Users</h1>

    <button (click)="dispatch.refreshed()">Refresh</button>
  `,
})
export class UsersComponent {
  readonly usersStore = inject(UsersStore);
  readonly dispatch = injectDispatch(usersPageEvents);

  constructor() {
    this.dispatch.opened();
  }
}

Scaling Up

As applications grow in complexity, reducers and effects can be extracted into standalone features to improve maintainability.

Extracted Reducer

export function withUsersReducer() {
  return signalStoreFeature(
    { state: type<EntityState<User> & RequestStatusState>() },
    withReducer(
      on(usersPageEvents.opened, usersPageEvents.refreshed, setPending),
      on(usersApiEvents.loadedSuccess, ({ payload }) => [
        setAllEntities(payload),
        setFulfilled(),
      ]),
      on(usersApiEvents.loadedFailure, ({ payload }) => setError(payload)),
    ),
  );
}

Extracted Effects

export function withUsersEffects() {
  return signalStoreFeature(
    withEffects(
      (
        store,
        events = inject(Events),
        usersService = inject(UsersService),
      ) => ({
        loadUsers$: events
          .on(usersPageEvents.opened, usersPageEvents.refreshed)
          .pipe(
            exhaustMap(() =>
              usersService.getAll().pipe(
                mapResponse({
                  next: (users) => usersApiEvents.loadedSuccess(users),
                  error: (error: { message: string }) =>
                    usersApiEvents.loadedFailure(error.message),
                }),
              ),
            ),
          ),
        logError$: events
          .on(usersApiEvents.loadedFailure)
          .pipe(tap(({ payload }) => console.log(payload))),
      }),
    ),
  );
}

Final Store Composition

export const UsersStore = signalStore(
  { providedIn: 'root' },
  withEntities<User>(),
  withRequestStatus(),
  withUsersReducer(),
  withUsersEffects(),
);

Key Takeaways 🔑

The Events plugin:

Combines proven patterns from Flux, NgRx Store, NgRx Effects, and RxJS.
Seamlessly integrates with existing SignalStore features.
Extends Flux architecture with powerful customization options.
Unifies local and global state management with a single approach.

Upcoming NgRx Workshops 🎓

With NgRx usage continuing to grow with Angular, many developers and teams still need guidance on how to architect and build enterprise-grade Angular applications. We are excited to introduce upcoming workshops provided directly by the NgRx team!

We're offering one to three full-day workshops that cover the basics of NgRx to the most advanced topics. Whether your teams are just starting with NgRx or have been using it for a while - they are guaranteed to learn new concepts during these workshops.

Visit our workshops page for more details. The next workshops are scheduled for:

June 11-13 (EU Time) | Registration
September 24-26 (US Time) | Registration
October 8-10 (EU Time) | Registration

Thanks to All Our Contributors and Sponsors! 🏆

NgRx continues to be a community-driven project. Design, development, documentation, and testing - all are done with the help of the community. Visit our community contributors section to see every person who has contributed to the framework.

If you are interested in contributing, visit our GitHub page and look through our open issues, some marked specifically for new contributors. We also have active GitHub discussions for new features and enhancements.

We want to give a big thanks to our Gold sponsor, Nx! Nx has been a longtime promoter of NgRx as a tool for building Angular applications and is committed to supporting open-source projects that they rely on.

We want to thank our Bronze sponsor, House of Angular!

Lastly, we also want to thank our individual sponsors who have donated once or monthly.

Sponsor NgRx 🤝

If you are interested in sponsoring the continued development of NgRx, please visit our GitHub Sponsors page for different sponsorship options, or contact us directly to discuss other sponsorship opportunities.

Announcing NgRx Signals v18: State Encapsulation, Private Store Members, Enhanced Entity Management, and more!

Marko Stanimirović — Thu, 25 Jul 2024 13:24:14 +0000

We are pleased to announce the latest major version of NgRx Signals, featuring exciting new features, bug fixes, and other updates.

NgRx Signals Are Now Stable! 🎉

As of version 18, the @ngrx/signals package is out of developer preview and is now production-ready.

State Encapsulation 🔒

In previous versions, SignalStore's state could be updated from the outside.

// v17:
export const CounterStore = signalStore(
  withState({ count: 0 }),
  withMethods((store) => ({
    setCount(count: number): void {
      patchState(store, { count }); // ✅
    },
  }))
);

// ===

const store = inject(CounterStore);
patchState(store, { count: 10 }); // ✅

In version 18, the state is protected from external modifications by default, ensuring a consistent and predictable data flow.

// v18:
const CounterStore = signalStore(
  withState({ count: 0 }),
  withMethods((store) => ({
    setCount(count: number): void {
      patchState(store, { count }); // ✅
    },
  }))
);

// ===

const store = inject(CounterStore);
patchState(store, { count: 10 }); // ❌ compilation error

However, for more flexibility in some cases, external updates to the state can be enabled by setting the protectedState option to false when creating a SignalStore.

const CounterStore = signalStore(
  { protectedState: false }, // 👈
  withState({ count: 0 })
);

// ===

const store = inject(CounterStore);
// ⚠️ The state is unprotected from external modifications.
patchState(store, { count: 10 });

💡 For backward compatibility, the migration schematic that adds protectedState: false to all existing signal stores is automatically executed on upgrade.

Ensuring Integrity of Store Members 👨‍⚕️

As of version 18, overriding SignalStore members is not allowed. If any store member is accidentally overridden, a warning will be displayed in development mode.

const CounterStore = signalStore(
  withState({ count: 0 }),
  withMethods(() => ({
    // ⚠️ @ngrx/signals: SignalStore members cannot be overridden.
    count(): void {},
  }))
);

Private Store Members 🛡️

SignalStore allows defining private members that cannot be accessed from outside the store by using the _ prefix. This includes root-level state slices, computed signals, and methods.

const CounterStore = signalStore(
  withState({
    count1: 0,
    // 👇 private state slice
    _count2: 0,
  }),
  withComputed(({ count1, _count2 }) => ({
    // 👇 private computed signal
    _doubleCount1: computed(() => count1() * 2),
    doubleCount2: computed(() => _count2() * 2),
  })),
  withMethods((store) => ({
    increment1(): void { /* ... */ },
    // 👇 private method
    _increment2(): void { /* ... */ },
  })),
);

// ===

const store = inject(CounterStore);

store.count1(); // ✅
store._count2(); // ❌ compilation error

store._doubleCount1(); // ❌ compilation error
store.doubleCount2(); // ✅

store.increment1(); // ✅
store._increment2(); // ❌ compilation error

💡 Learn more about private store members in the Private Store Members guide.

State Tracking 🕵

State tracking enables the implementation of custom SignalStore features such as logging, state undo/redo, and storage synchronization.

In previous versions, it was possible to track SignalStore state changes by using the getState function with effect.

const CounterStore = signalStore(
  withState({ count: 0 }),
  withMethods((store) => ({
    increment(): void { /* ... */ },
  })),
  withHooks({
    onInit(store) {
      effect(() => {
        // 👇 The effect is re-executed on state change.
        const state = getState(store);
        console.log('counter state', state);
      });

      setInterval(() => store.increment(), 1_000);
    },
  })
);

Due to the effect glitch-free behavior, if the state is changed multiple times in the same tick, the effect function will be executed only once with the final state value. While the asynchronous effect execution is beneficial for performance reasons, functionalities such as state undo/redo require tracking all SignalStore's state changes without coalescing state updates in the same tick.

In this release, the @ngrx/signals package provides the watchState function, which allows for synchronous tracking of SignalStore's state changes. It accepts a SignalStore instance as the first argument and a watcher function as the second argument.

By default, the watchState function needs to be executed within an injection context. It is tied to its lifecycle and is automatically cleaned up when the injector is destroyed.

const CounterStore = signalStore(
  withState({ count: 0 }),
  withMethods((store) => ({
    increment(): void { /* ... */ },
  })),
  withHooks({
    onInit(store) {
      watchState(store, (state) => {
        console.log('[watchState] counter state', state);
      }); // logs: { count: 0 }, { count: 1 }, { count: 2 }

      effect(() => {
        console.log('[effect] counter state', getState(store));
      }); // logs: { count: 2 }

      store.increment();
      store.increment();
    },
  })
);

In the example above, the watchState function will execute the provided watcher 3 times: once with the initial counter state value and two times after each increment. Conversely, the effect function will be executed only once with the final counter state value.

💡 Learn more about the watchState function in the State Tracking guide.

Enhanced Entity Management 🧩

In version 18, the @ngrx/signals/entities plugin received several enhancements.

`selectId`

In previous versions, updating an entity collection with a custom identifier was performed using the idKey property.

// v17:
type Todo = { _id: number; text: string };

const TodosStore = signalStore(
  withEntities<Todo>(),
  withMethods((store) => ({
    addTodo(todo: Todo): void {
      patchState(store, addEntity(todo, { idKey: '_id' }));
    },
  }))
);

If an entity has a composite identifier (a combination of two or more properties), idKey cannot be used.

In this release, selectId is introduced instead of idKey for better flexibility.

// v18:
type Todo = { _id: number; text: string };

const selectId: SelectEntityId<Todo> = (todo) => todo._id;

const TodosStore = signalStore(
  withEntities<Todo>(),
  withMethods((store) => ({
    addTodo(todo: Todo): void {
      patchState(store, addEntity(todo, { selectId }));
    },
  }))
);

`entityConfig`

The entityConfig function reduces repetitive code when defining a custom entity configuration and ensures strong typing. It accepts a config object where the entity type is required, and the collection name and custom ID selector are optional.

const todoConfig = entityConfig({
  entity: type<Todo>(),
  collection: 'todo',
  selectId: (todo) => todo._id,
});

const TodosStore = signalStore(
  withEntities(todoConfig),
  withMethods((store) => ({
    addTodo(todo: Todo): void {
      patchState(store, addEntity(todo, todoConfig));
    },
  }))
);

💡 Learn more about the @ngrx/signals/entities plugin in the Entity Management guide.

Upgrading to NgRx Signals 18 🛠️

To start using NgRx Signals 18, make sure to have the following minimum versions installed:

Angular version 18.x
Angular CLI version 18.x
TypeScript version 5.4.x

NgRx supports using the Angular CLI ng update command to update your NgRx packages. To update the @ngrx/signals package to the latest version, run the command:

ng update @ngrx/signals@18

Upcoming NgRx Workshops 🎓

Visit our workshops page to sign up from our list of upcoming workshops. The next workshops are scheduled for September 18-20 (US-based time) and October 16-18 (Europe-based time). The early bird discount is still active!

Welcoming New Additions to the NgRx Team 💪

After a long break, Mike Ryan is back on the NgRx core team! As one of the original co-creators of NgRx, Mike wrote the first lines of code for the @ngrx/effects, @ngrx/entity, and @ngrx/store-devtools packages. We are thrilled to have him return to the team! Welcome back, Mike! 💜

We have another exciting announcement: Rainer Hahnekamp has joined the NgRx team as a trusted collaborator! Rainer is a Google Developer Expert in Angular, an active contributor to the NgRx repository, a maintainer of the NgRx Toolkit community plugin, and the creator of numerous insightful articles and videos on NgRx. Welcome aboard, Rainer! 🚀

Thanks to All Our Contributors and Sponsors! 🏆

We want to thank our Bronze sponsor, House of Angular!

Lastly, we also want to thank our individual sponsors who have donated once or monthly.

Sponsor NgRx 🤝

Announcing NgRx v16: Integration with Angular Signals, Functional Effects, Standalone Schematics, and more!

Marko Stanimirović — Tue, 09 May 2023 16:40:57 +0000

We are pleased to announce the latest major version of the NgRx framework with some exciting new features, bug fixes, and other updates.

NgRx 🤝 Signals

As part of the v16 release, Angular introduced a new reactivity model powered by signals. Signal APIs provide a simple way of managing state and will significantly improve the rendering performance of Angular applications in the future.

In v16, NgRx Store has a new method, selectSignal, which provides integration with Angular Signals. This method expects a selector as an input argument and returns a signal of the selected state slice. It has a similar signature to the select method, but unlike select, selectSignal returns a signal instead of an observable.

import { Component, inject } from '@angular/core';
import { NgFor } from '@angular/common';
import { Store } from '@ngrx/store';

import { selectUsers } from './users.selectors';

@Component({
  standalone: true,
  imports: [NgFor],
  template: `
    <h1>Users</h1>

    <ul>
      <li *ngFor="let user of users()">
        {{ user.name }}
      </li>
    </ul>
  `
})
export class UsersComponent {
  private readonly store = inject(Store);

  // type: Signal<User[]>
  readonly users = this.store.selectSignal(selectUsers);
}

ComponentStore also provides the selectSignal method, which has two signatures. The first signature creates a signal from the provided state projector function, while the second creates a signal by combining provided signals, similar to the select method that combines provided observables.

import { Injectable } from '@angular/core';
import { ComponentStore } from '@ngrx/component-store';

import { User } from './user.model';

type UsersState = { users: User[]; query: string };

@Injectable()
export class UsersStore extends ComponentStore<UsersState> {
  // type: Signal<User[]>
  readonly users = this.selectSignal((s) => s.users);
  // type: Signal<string>
  readonly query = this.selectSignal((s) => s.query);
  // type: Signal<User[]>
  readonly filteredUsers = this.selectSignal(
    this.users,
    this.query,
    (users, query) =>
      users.filter(({ name }) => name.includes(query))
  );
}

Similar to the computed function, the selectSignal method also accepts the equality function to stop the recomputation of the deeper dependency chain if two values are determined to be equal.

The state signal is another addition to the ComponentStore. Instead of using selectSignal, it can be used together with the computed function to create derived signals.

import { computed, Injectable } from '@angular/core';
import { ComponentStore } from '@ngrx/component-store';

import { User } from './user.model';

type UsersState = { users: User[]; query: string };

@Injectable()
export class UsersStore extends ComponentStore<UsersState> {
  readonly users = computed(() => this.state().users);
  readonly query = computed(() => this.state().query);

  readonly filteredUsers = computed(() =>
    this.users().filter(({ name }) => name.includes(this.query()))
  );
}

Functional Effects 🔥

In the past, we couldn't create NgRx effects outside of classes because Angular only supported constructor-based dependency injection. However, things have changed with the inject function and we can now inject tokens and services outside of class constructors. This provides the ability to define NgRx effects as functions outside of effect classes.

Let's see the functional effects in action!

To create a functional effect, add the functional: true flag to the effect config. Then, to inject services into the effect, use the inject function.

import { inject } from '@angular/core';
import { catchError, exhaustMap, map, of, tap } from 'rxjs';
import { Actions, createEffect, ofType } from '@ngrx/effects';

import { UsersService } from './users.service';
import { UsersPageActions } from './users-page.actions';
import { UsersApiActions } from './users-api.actions';

export const loadUsers = createEffect(
  (
    actions$ = inject(Actions),
    usersService = inject(UsersService)
  ) => {
    return actions$.pipe(
      ofType(UsersPageActions.opened),
      exhaustMap(() =>
        usersService.getAll().pipe(
          map((users) =>
            UsersApiActions.usersLoadedSuccess({ users })
          ),
          catchError((error) =>
            of(UsersApiActions.usersLoadedFailure({ error }))
          )
        )
      )
    );
  },
  { functional: true }
);

export const displayErrorAlert = createEffect(
  () => {
    return inject(Actions).pipe(
      ofType(UsersApiActions.usersLoadedFailure),
      tap(({ error }) => alert(error.message))
    );
  },
  { functional: true, dispatch: false }
);

💡 To make testing easier, it's recommended to inject all dependencies as effect function arguments. However, it's also possible to inject dependencies in the effect function body. In that case, the inject function must be called within the injection context.

To register functional effects, pass the dictionary of effects to the provideEffects function.

import { bootstrapApplication } from '@angular/platform-browser';
import { provideStore } from '@ngrx/store';
import { provideEffects } from '@ngrx/effects';

import { AppComponent } from './app.component';
import * as usersEffects from './users.effects';

bootstrapApplication(AppComponent, {
  providers: [
    provideStore(),
    provideEffects(usersEffects),
  ],
});

💡 In module-based Angular applications, functional effects can be registered using the EffectsModule.forRoot or EffectsModule.forFeature methods.

Functional effects can be tested like any other function. If all dependencies are injected as effect function arguments, TestBed is not required to mock dependencies. Instead, fake instances can be passed as input arguments to the functional effect.

import { of } from 'rxjs';

import { loadUsers } from './users.effects';
import { UsersService } from './users.service';
import { usersMock } from './users.mock';
import { UsersPageActions } from './users-page.actions';
import { UsersApiActions } from './users-api.actions';

it('loads users successfully', (done) => {
  const usersServiceMock = {
    getAll: () => of(usersMock),
  } as UsersService;
  const actionsMock$ = of(UsersPageActions.opened());

  loadUsers(actionsMock$, usersServiceMock).subscribe((action) => {
    expect(action).toEqual(
      UsersApiActions.usersLoadedSuccess({ users: usersMock })
    );
    done();
  });
});

Feature Creator Enhancements 🤩

The createFeature function now allows adding additional selectors to the feature object using the extraSelectors factory.

import { createFeature, createReducer } from '@ngrx/store';

import { User } from './user.model';

type State = { users: User[]; query: string };

const initialState: State = {
  users: [],
  query: '',
};

export const usersFeature = createFeature({
  name: 'users',
  reducer: createReducer(initialState, /* case reducers */),
  // 👇 adding extra selectors to the `usersFeature` object
  extraSelectors: ({ selectUsers, selectQuery }) => ({
    selectFilteredUsers: createSelector(
      selectUsers,
      selectQuery,
      (users, query) =>
        users.filter((user) => user.name.includes(query)),
    ),
  }),
});

The extraSelectors factory can also be used to add derived entity selectors to the feature object in a simple and elegant way.

import { createFeature, createReducer } from '@ngrx/store';
import { createEntityAdapter } from '@ngrx/entity';

import { User } from './user.model';

const adapter = createEntityAdapter<User>();
const initialState = adapter.getInitialState();

export const usersFeature = createFeature({
  name: 'users',
  reducer: createReducer(initialState, /* case reducers */),
  // 👇 adding entity selectors to the `usersFeature` object
  extraSelectors: ({ selectUsersState }) =>
    adapter.getSelectors(selectUsersState)
});

Special thanks to Armen Vardanyan for writing documentation for this feature!

Action Group Creator Improvements 👌

We received great feedback on the createActionGroup function so far. It provides a better developer experience and significantly reduces lines of code in action files. However, when event names are defined in title case format, it can be challenging to search for unused action creators because their names are automatically generated by camel-casing the event names.

In v16, the createActionGroup function provides the ability to define event names in the camel case format as well, so action creators will have the same names as events. This makes it easier to search for their usage within the codebase.

import { createActionGroup } from '@ngrx/store';

import { User } from './user.model';

export const UsersApiActions = createActionGroup({
  name: 'Users API',
  events: {
    usersLoadedSuccess: props<{ users: User[] }>(),
    usersLoadedFailure: props<{ errorMsg: string }>(),
  },
});

// generated action creators:
const {
  usersLoadedSuccess, // type: "[Users API] usersLoadedSuccess"
  usersLoadedFailure, // type: "[Users API] usersLoadedFailure"
} = UsersApiActions;

Enhanced Schematics and Standalone Support 🚀

In the last few major releases, many enhancements and new features have been added to the NgRx framework. However, the @ngrx/schematics package hadn't received significant updates.

In version 16, NgRx Schematics have been improved and now use the latest features, such as createFeature and createActionGroup, thanks to the contributions of Marco Endres!

But that's not all! In addition to these improvements, version 16 also introduces the ability to add NgRx packages to standalone Angular applications using the ng add command. For example, we can now add the @ngrx/store package with initial configuration to a standalone Angular application by running the following command:

ng add @ngrx/store

Similarly, we can add other NgRx packages, such as @ngrx/effects, @ngrx/store-devtools, and @ngrx/router-store to standalone applications using the ng add command.

Huge thanks to Dmytro Mezhenskyi for contributing to this feature!

Simplified View Model Selectors 🪄

The createSelector function now accepts a dictionary of selectors as an input and returns a dictionary of state slices selected by the provided selectors as a result. This feature simplifies the creation of view model selectors by reducing repetitive code in projector functions.

import { createSelector } from '@ngrx/store';

// before:
export const selectUsersPageViewModel = createSelector(
  selectFilteredUsers,
  selectActiveUser,
  selectQuery,
  selectIsLoading,
  (users, activeUser, query, isLoading) => ({
    users,
    activeUser,
    query,
    isLoading,
  })
);

// after:
export const selectUsersPageViewModel = createSelector({
  users: selectFilteredUsers,
  activeUser: selectActiveUser,
  query: selectQuery,
  isLoading: selectIsLoading,
});

New tapResponse Signature 😎

The tapResponse operator has a new signature that allows us to provide the observer object as an input argument, along with the finalize callback. Using this new signature, we can simplify the code and make it more readable.

import { inject, Injectable } from '@angular/core';
import { exhaustMap } from 'rxjs';
import { ComponentStore, tapResponse } from '@ngrx/component-store';

import { UsersService } from './users.service';
import { User } from './user.model';

type UsersState = { users: User[]; isLoading: boolean };

@Injectable()
class UsersStore extends ComponentStore<UsersState> {
  private readonly usersService = inject(UsersService);

  readonly loadUsers = this.effect<void>(
    exhaustMap(() => {
      this.patchState({ isLoading: true });

      return this.usersService.getAll().pipe(
        tapResponse({
          next: (users) => this.patchState({ users }),
          error: console.error,
          // 👇 set loading to false on complete or error
          finalize: () => this.patchState({ isLoading: false }),
        })
      );
    })
  );
}

Standalone Component APIs 😍

LetDirective and PushPipe are standalone in version 16, so we can directly add them to the imports of a standalone component or NgModule, instead of using LetModule and PushModule.

import { Component } from '@angular/core';
import { LetDirective, PushPipe } from '@ngrx/component';

@Component({
  // ... other metadata
  standalone: true,
  imports: [
    // ... other imports
    LetDirective,
    PushPipe,
  ],
})
export class UsersComponent {}

We would like to thank Stefanos Lignos for contributing to this feature!

New Router Selector 🤘

We've added a new router selector that selects the route data property by name.

import { createSelector } from '@ngrx/store';
import { getRouterSelectors } from '@ngrx/router-store';

const { selectRouteDataParam } = getRouterSelectors();

export const selectFullNameFromRoute = createSelector(
  selectRouteDataParam('firstName'),
  selectRouteDataParam('lastName'),
  (firstName, lastName) => `${firstName} ${lastName}`
);

Many thanks to Samuel Fernández for contributing to this feature!

NgRx SignalStore 💡

We've recently opened an RFC for a new state management solution that will provide first-class support for Angular Signals. The design of the SignalStore APIs is still under consideration, so we'd love to hear your thoughts! If you're interested, take a look and let us know what you think.

Deprecations and Breaking Changes 💥

This release contains bug fixes, deprecations, and breaking changes. For most of these deprecations or breaking changes, we've provided a migration that automatically runs when you upgrade your application to the latest version.

Take a look at the version 16 migration guide for complete information regarding migrating to the latest release. The complete CHANGELOG can be found in our GitHub repository.

Upgrading to NgRx 16 🗓️

To start using NgRx 16, make sure to have the following minimum versions installed:

Angular version 16.x
Angular CLI version 16.x
TypeScript version 5.x
RxJS version ^6.5.x or ^7.5.x

NgRx supports using the Angular CLI ng update command to update your NgRx packages. To update your packages to the latest version, run the command:

ng update @ngrx/store

If your project uses @ngrx/component-store, but not @ngrx/store, run the following command:

ng update @ngrx/component-store

Enterprise Support 👨‍🏫

The NgRx collection of libraries will always remain open-source, MIT-licensed, and free to use. At the same time, we hear from companies that designing high-quality architecture could be challenging and additional help and guidance are needed.

Participating members of the NgRx team now offer paid support for those interested in NgRx workshops, training on best practices, architecture review, and more.

Visit our Enterprise Support page to learn more.

Swag Store and Discord Server 🦺

You can get official NgRx swag through our store! T-shirts with the NgRx logo are available in many different sizes, materials, and colors. We will look at adding new items to the store such as stickers, magnets, and more in the future. Visit our store to get your NgRx swag today!

Join our Discord server for those who want to engage with other members of the NgRx community, old and new.

Contributing to NgRx 🥰

We're always trying to improve the docs and keep them up-to-date for users of the NgRx framework. To help us, you can start contributing to NgRx. If you're unsure where to start, come take a look at our contribution guide and watch the introduction video Jan-Niklas Wortmann and Brandon Roberts have made to help you get started.

Thanks to all our contributors and sponsors!

NgRx continues to be a community-driven project. Design, development, documentation, and testing all are done with the help of the community. We've recently added a community section to the NgRx team page that lists every person that has contributed to the platform.

We would like to thank the contributors that helped to work towards this release of NgRx: Andreas Pramendorfer, André Escocard, Andrés Villanueva, Armen Vardanyan, Ben Lesh, briannarenni, Cameron Maunder, coder925, CoranH, Cédric Duffournet, Daniel Sogl, Dmytro Mezhenskyi, Fabien Wautriche, Fábio Englert Moutinho, Jerome Wirth, Jobayer Ahmed, jonz94, Jovan Mitrović, Kyler Johnson, Laforge Thomas, Manuel A Martin Callejo, Manuel Geier, Marco Endres, Michael Egger-Zikes, Mike Drakoulelis, naticaceres, Samruddhi Khandale, Samuel Fernández, Soumya Kushwaha, Stefanos Lignos, Taylor Ackley, Thomas Waldbillig, zakaria-bali, zbarbuto.

We want to give a big thanks to our Silver sponsor, Nx! Nx has been a longtime promoter of NgRx as a tool for building large Angular applications, and is committed to supporting open source projects that they rely on.

We also want to thank our Bronze sponsor, House of Angular!

Sponsor NgRx 💰

We are looking for our next Gold sponsor, so if your company wants to sponsor the continued development of NgRx, please visit our GitHub Sponsors page for different sponsorship options, or contact us directly to discuss other sponsorship opportunities.

Building Reactive Angular Templates with NgRx Component

Marko Stanimirović — Sun, 19 Jun 2022 12:52:31 +0000

In this article, we'll look into the @ngrx/component library used to build reactive Angular templates in a performant way. It contains a set of declarables that are primarily used for rendering observable events and can work in both zone-full and zone-less mode.

Installation

To install the @ngrx/component package, run one of the following commands:

// Angular CLI
ng add @ngrx/component

// NPM
npm i @ngrx/component

// Yarn
yarn add @ngrx/component

Push Pipe

The ngrxPush pipe is used for displaying observable values in the template. To use it, import the PushModule to an Angular module or standalone component:

import { PushModule } from '@ngrx/component';

@Component({
  // ... other metadata
  standalone: true,
  imports: [
    // ... other imports
    PushModule,
  ],
})
export class ProductDetailsComponent {
  readonly product$ = this.store.select(selectActiveProduct);

  constructor(private readonly store: Store) {}
}

💡 PushModule is available since version 14. If you're using an older version of the @ngrx/component package, import the ReactiveComponentModule.

The ngrxPush pipe is an alternative to the async pipe and can be used in the following way:

<ngrx-product-form
  [product]="product$ | ngrxPush"
></ngrx-product-form>

Similar to the async pipe, the ngrxPush pipe returns the last emitted value of the passed observable or undefined if there are no emitted values. However, there are two key differences compared to the async pipe:

The ngrxPush pipe will not mark the host component as dirty when an observable emits the same values in a row.
The ngrxPush pipe will not mark the host component as dirty when an observable emits values synchronously.
The ngrxPush pipe will trigger change detection when an observable emits a new value in zone-less mode.

💡 Since version 14, the @ngrx/component package uses the global rendering strategy in both zone-full and zone-less mode. In previous versions, it used the native local rendering strategy in zone-less mode, which caused performance issues.

Let Directive

The *ngrxLet directive is used for rendering observable events in the template. To use it, import the LetModule to an Angular module or standalone component:

import { LetModule } from '@ngrx/component';

@Component({
  // ... other metadata
  standalone: true,
  imports: [
    // ... other imports
    LetModule,
  ],
})
export class ProductListComponent {
  readonly products$ = this.productsService.getProducts({ limit: 10 });
  readonly totalCount$ = this.productsService.getTotalCount();

  constructor(private readonly productsService: ProductsService) {}
}

💡 LetModule is available since version 14. If you're using an older version of the @ngrx/component package, import the ReactiveComponentModule.

The *ngrxLet directive can be used in the following way:

<ng-container *ngrxLet="totalCount$ as totalCount">
  <h2>Products ({{ totalCount }})</h2>

  <p *ngIf="!totalCount" class="info-alert">
    There are no products.
  </p>
</ng-container>

At first, it seems that we can achieve the same result using the *ngIf directive and async pipe:

<ng-container *ngIf="totalCount$ | async as totalCount">
  <h2>Products ({{ totalCount }})</h2>

  <p *ngIf="!totalCount" class="info-alert">
    There are no products.
  </p>
</ng-container>

However, the *ngIf directive will only create an embedded view if the totalCount is not zero (truthy value), but not if it is zero (falsy value). On the other hand, the *ngrxLet directive will create an embedded view when an observable emits a value, regardless of whether it is truthy or falsy.

Tracking Different Observable Events

The *ngrxLet directive provides the ability to display different content based on the current observable state. For example, we can display an error alert if an observable emits the error event:

<ng-container *ngrxLet="products$ as products; error as error">
  <ngrx-product-card
    *ngFor="let product of products"
    [product]="product"
  ></ngrx-product-card>

  <p *ngIf="error" class="error-alert">{{ error.message }}</p>
</ng-container>

💡 Displaying thrown error is possible since version 14. In previous versions, the value of error is true when the passed observable emits the error event.

In addition to error, we can also track the complete event:

<ng-container
  *ngrxLet="saveProgress$ as progress; complete as complete"
>
  <mat-progress-spinner
    [value]="progress"
    mode="determinate"
  ></mat-progress-spinner>

  <p *ngIf="complete" class="success-alert">
    Product is successfully saved!
  </p>
</ng-container>

Combining Multiple Observables

The *ngrxLet directive can be also used with a dictionary of observables. This feature provides the ability to create a view model object in the template:

<ng-container *ngrxLet="{ products: products$, query: query$ } as vm">
  <app-search-bar [query]="vm.query"></app-search-bar>
  <app-product-list [products]="vm.products"></app-product-list>
</ng-container>

💡 Combining multiple observables in the template using the *ngrxLet directive is available since version 15.

Using Suspense Template

Also, there is an option to pass the suspense template to the *ngrxLet directive:

<ng-container *ngrxLet="products$ as products; suspenseTpl: loading">
  <ngrx-product-card
    *ngFor="let product of products"
    [product]="product"
  ></ngrx-product-card>
</ng-container>

<ng-template #loading>
  <mat-spinner></mat-spinner>
</ng-template>

The suspense template will be rendered when the passed observable is in a suspense state. In the example above, the loading spinner will be displayed until the products$ observable emits a list of products. When this happens, the loading spinner will be removed from the DOM and products will be displayed.

💡 Using suspense template with the *ngrxLet directive is available since version 14.

Using Aliases for Non-Observable Values

In addition to observables and promises, the *ngrxLet directive can also accept static (non-observable) values as an input argument. This feature provides the ability to create readable templates by using aliases for deeply nested properties:

<ng-container *ngrxLet="productForm.controls.price as price">
  <input type="number" [formControl]="price" />

  <ng-container *ngIf="price.errors && (price.touched || price.dirty)">
    <p *ngIf="price.errors.required">Price is a required field.</p>
    <p *ngIf="price.errors.min">Price cannot be a negative number.</p>
  </ng-container>
</ng-container>

💡 Passing non-observable values to the *ngrxLet directive is available since version 14.

Summary

Many new and powerful features have been added in recent versions:

Separate modules for LetDirective and PushPipe
Displaying emitted error in the template
Using aliases for non-observable values
Combining multiple observables in the template
Handling suspense state in the template
Strong typing for LetDirective and PushPipe

Also, this library has been almost completely rewritten for better performance. If you haven't used it before, give it a try and let us know your impressions!

In version 15, the @ngrx/component package is no longer marked as experimental and is now marked as stable. By the way, it recently reached 30k downloads per week on NPM! 🎉

Resources

Official docs of the @ngrx/component package

Peer Reviewers

Big thanks to Brandon Roberts and Tim Deschryver for giving me helpful suggestions on this article!

Using NgRx Packages with Standalone Angular Features

Marko Stanimirović — Tue, 14 Jun 2022 13:06:04 +0000

⚠️ This article was written before we released standalone NgRx APIs. They are available from v14.3.0. Read more here.

In this article, we'll look into the standalone Angular APIs introduced in version 14. We will then explore ways how to use NgRx packages with standalone features.

Standalone Angular APIs
- Creating Standalone Components
- Interop with Angular Modules
- Configuring Angular Router
Angular Modules from NgRx Packages
- Using NgRx Modules with Standalone Angular APIs
Standalone NgRx APIs
Source Code
Resources
Peer Reviewers

Standalone Angular APIs

With standalone Angular APIs, we can build Angular applications without NgModules. In other words, components, directives, and pipes can be used without declaration in any Angular module.

💡 In Angular 14, standalone APIs are in developer preview and may change in the future without backward compatibility.

Creating Standalone Components

To create a standalone component, we need to set the standalone flag to true and register template dependencies using the imports property within the component configuration. The imports array can accept Angular modules or other standalone components, directives, or pipes:

// header.component.ts

@Component({
  selector: 'app-header',
  template: `
    <a routerLink="/">Home</a>
    <a *ngIf="isAuthenticated$ | async" routerLink="/">Musicians</a>
  `,
  standalone: true,
  // importing modules whose declarables are used in the template
  imports: [CommonModule, RouterModule],
})
export class HeaderComponent {
  readonly isAuthenticated$ = this.authService.isAuthenticated$;

  constructor(private readonly authService: AuthService) {}
}

// app.component.ts

@Component({
  selector: 'app-root',
  template: `
    <app-header></app-header>
    <router-outlet></router-outlet>
  `,
  standalone: true,
  // importing `HeaderComponent` as a template dependency
  imports: [RouterModule, HeaderComponent],
})
export class AppComponent {}

AppModule is no longer required to bootstrap the application. Instead, we can use the bootstrapApplication function from the @angular/platform-browser package that accepts the root component as an input argument:

// main.ts

bootstrapApplication(AppComponent);

The bootstrapApplication function accepts an object with providers as a second argument, so we can provide services at the root level as follows:

bootstrapApplication(AppComponent, {
  providers: [
    { provide: ErrorHandler, useClass: CustomErrorHandler },
  ],
});

Interop with Angular Modules

Now the question is, how to provide services from existing Angular modules. Fortunately, there is a new function importProvidersFrom from the @angular/core package that accepts a sequence of Angular modules as an input argument and returns their providers as a result:

const providers = importProvidersFrom(
  HttpClientModule,
  // ... other modules
);

Providers returned by the importProvidersFrom function can be registered at the root level in the following way:

bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(HttpClientModule),
  ],
});

Configuring Angular Router

In Angular 14, there is an option to register providers at the route level by adding the providers array to the Route object. This gives the ability to define feature-level providers in the following way:

// musicians.routes.ts

export const musiciansRoutes: Route[] = [
  {
    path: '',
    // registering providers for the route and all its children
    providers: [
      { provide: MusiciansService, useClass: MusiciansHttpService },
      importProvidersFrom(NgModule1, NgModule2),
    ],
    children: [
      {
        path: '',
        component: MusicianListComponent,
      },
      {
        path: ':id',
        component: MusicianDetailsComponent,
        canActivate: [MusicianExistsGuard],
      },
    ],
  },
];

Then, we can lazy load feature routes using the loadChildren property in the application routes configuration:

// app.routes.ts

export const appRoutes: Route[] = [
  { path: '', component: HomeComponent },
  {
    path: 'musicians',
    // importing `musiciansRoutes` using the `loadChildren` property
    loadChildren: () =>
      import('@musicians/musicians.routes').then(
        (m) => m.musiciansRoutes
      ),
  },
];

The next step is to register application routes using the RouterModule as follows:

// main.ts

bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(RouterModule.forRoot(appRoutes)),
  ],
});

When bootstrapping the application, Angular will initialize the root RouterModule, register application routes, and provide Router, ActivatedRoute, and other providers from the RouterModule at the root level.

Angular Modules from NgRx Packages

As we have seen in the case of the RouterModule, Angular modules are not only used to declare components or provide services. They are also used to configure various application and library functionalities. In the case of NgRx, we use the EffectsModule.forRoot method to provide the Actions observable at the root level of an Angular application, initialize the effects runner, and run root effects. Therefore, importing root modules from other NgRx packages will configure their functionalities and/or provide services:

// app.module.ts

@NgModule({
  imports: [
    // provide `Store` at the root level
    // register initial reducers
    // initialize runtime checks mechanism
    StoreModule.forRoot({ router: routerReducer, auth: authReducer }),
    // connect NgRx Store with Angular Router
    StoreRouterConnectingModule.forRoot(),
    // connect NgRx Store with Redux Devtools extension
    StoreDevtoolsModule.instrument(),
    // provide `Actions` at the root level
    // initialize effects runner
    // run root effects
    EffectsModule.forRoot([RouterEffects, AuthEffects]),
  ],
})
export class AppModule {}

Also, NgRx exposes APIs for registering additional reducers and effects in feature modules:

// musicians.module.ts

@NgModule({
  imports: [
    // register feature reducer
    StoreModule.forFeature('musicians', musiciansReducer),
    // run feature effects
    EffectsModule.forFeature([MusiciansApiEffects]),
  ],
})
export class MusiciansModule {}

Using NgRx Modules with Standalone Angular APIs

Similar to the root RouterModule, NgRx modules can be configured at the application level using the bootstrapApplication function:

// main.ts

bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(
      RouterModule.forRoot(appRoutes),

      // configure NgRx modules
      StoreModule.forRoot({
        router: routerReducer,
        auth: authReducer,
      }),
      StoreRouterConnectingModule.forRoot(),
      StoreDevtoolsModule.instrument(),
      EffectsModule.forRoot([RouterEffects, AuthEffects])
    ),
  ],
});

The feature reducer and effects can be lazily registered in the route configuration for a specific feature as follows:

// musicians.routes.ts

export const musiciansRoutes: Route[] = [
  {
    path: '',
    providers: [
      importProvidersFrom(
        // register feature reducer
        StoreModule.forFeature('musicians', musiciansReducer),
        // run feature effects
        EffectsModule.forFeature([MusiciansApiEffects])
      ),
    ],
    children: [
      {
        path: '',
        component: MusicianListComponent,
      },
      {
        path: ':id',
        component: MusicianDetailsComponent,
        canActivate: [MusicianExistsGuard],
      },
    ],
  },
];

Standalone NgRx APIs

Instead of using NgModules to configure NgRx packages and/or provide their services, we could use functions for a "module-free" developer experience. For example, we could use a function named provideStore instead of StoreModule.forRoot. The same principle can be applied to other NgRx packages. Using standalone NgRx functions would look like this:

// main.ts

bootstrapApplication(AppComponent, {
  providers: [
    // alternative to `StoreModule.forRoot`
    provideStore({ router: routerReducer, auth: AuthReducer }),
    // alternative to `StoreRouterConnectingModule.forRoot`
    provideRouterStore(),
    // alternative to `StoreDevtoolsModule.instrument`
    provideStoreDevtools(),
    // alternative to `EffectsModule.forRoot`
    provideEffects([RouterEffects, AuthEffects]),
  ),
});

Feature reducers and effects would also be registered using functions instead of NgModules:

// musicians.routes.ts

export const musiciansRoutes: Route[] = [
  {
    path: '',
    providers: [
      // alternative to `StoreModule.forFeature`
      provideStoreFeature('musicians', musiciansReducer),
      // alternative to `EffectsModule.forFeature`
      provideFeatureEffects([MusiciansApiEffects]),
    ],
    children: [
      {
        path: '',
        component: MusicianListComponent,
      },
      {
        path: ':id',
        component: MusicianDetailsComponent,
        canActivate: [MusicianExistsGuard],
      },
    ],
  },
];

💡 The design of standalone NgRx APIs is still under consideration. If you have any suggestions, leave a comment here.

Source Code

The source code of the proposed standalone NgRx APIs and sample project is available here.

Resources

Peer Reviewers

Many thanks to Tim Deschryver and Brandon Roberts for reviewing this article!

NgRx Action Group Creator

Marko Stanimirović — Tue, 03 May 2022 11:56:55 +0000

In this article, we'll explore a new feature from the @ngrx/store package - the createActionGroup function that is introduced in version 13.2.

Using Action Creator

We usually define action creators using the createAction function:

// products-page.actions.ts
import { createAction, props } from '@ngrx/store';

// defining an action without payload
export const opened = createAction('[Products Page] Opened');

// defining an action with payload using the `props` function
export const paginationChanged = createAction(
  '[Products Page] Pagination Changed',
  props<{ page: number; offset: number }>()
);

// defining an action with payload using the props factory
export const queryChanged = createAction(
  '[Product Page] Query Changed',
  (query: string) => ({ query })
);

In this example, we use the "[Source] Event Name" pattern to define action types where the source of each action is "Products Page". Also, the name of each action creator is equal to the camel-cased name of the event it expresses. For example, the action creator name for the "Pagination Changed" event is "paginationChanged".

💡 If you are not familiar with treating actions as unique events, learn more in this talk by Mike Ryan.

To use products page actions in the products container component, we usually use named import:

// products.component.ts
import * as ProductsPageActions from './products-page.actions';

@Component({ /* ... */ })
export class ProductsComponent implements OnInit {
  constructor(private readonly store: Store) {}

  ngOnInit(): void {
    this.store.dispatch(ProductsPageActions.opened());
  }
}

Another common practice is to create a barrel file with named exports from action files:

// products/actions/index.ts
export * as ProductsPageActions from './products-page.actions';
export * as ProductsApiActions from './products-api.actions';

Named exports can be further used in files where needed.

Using Action Group Creator

The createActionGroup function creates a group of action creators with the same source. It accepts an action group source and an event dictionary as input arguments, where an event is a key-value pair of an event name and event props:

// products-page.actions.ts
import { createActionGroup, emptyProps, props } from '@ngrx/store';

export const ProductsPageActions = createActionGroup({
  source: 'Products Page',
  events: {
   // defining an event without payload using the `emptyProps` function
    'Opened': emptyProps(),

    // defining an event with payload using the `props` function
    'Pagination Changed': props<{ page: number; offset: number }>(),

    // defining an event with payload using the props factory
    'Query Changed': (query: string) => ({ query }),
  },
});

💡 The emptyProps function is another addition to the @ngrx/store package. It is used to define an action without payload within an action group.

The createActionGroup function returns a dictionary of action creators where the name of each action creator is created by camel casing the event name, and the action type is created using the "[Source] Event Name" pattern:

// action type: [Products Page] Opened
ProductsPageActions.opened();

// action type: [Products Page] Pagination Changed
ProductsPageActions.paginationChanged({ page: 10, offset: 100 });

// action type: [Products Page] Query Changed
ProductsPageActions.queryChanged('ngrx');

Also, there is no longer a need for barrel files or named imports because the action group can be imported directly into another file:

// products.component.ts
import { ProductsPageActions } from './products-page.actions';

@Component({ /* ... */ })
export class ProductsComponent implements OnInit {
  constructor(private readonly store: Store) {}

  ngOnInit(): void {
    this.store.dispatch(ProductsPageActions.opened());
  }
}

If we create a new action using the createAction function by copying the previous one but accidentally forget to change its type, the compilation will pass. Fortunately, this is not the case with the createActionGroup function - we will get a compilation error if two actions from the same group have the same type.

Limitations

We can define different names for an event and an action creator using the createAction function:

export const productsLoadedSuccess = createAction(
  '[Products API] Products Are Loaded Successfully',
  props<{ products: Product[] }>()
);

In this example, the event name is "Products Are Loaded Successfully" and the action creator name is "productsLoadedSuccess". Unfortunately, this is not possible with the createActionGroup function, because the action creator name will be always equal to the camel-cased event name. So for the event name "Products Are Loaded Successfully", the action creator name will be "productsAreLoadedSuccessfully".

Conclusion

Action group creator improves developer experience by reducing code in action files. It eliminates the need to create barrel files or use named imports for actions, define the same action source in multiple places, and write the same name for the event and the action creator twice. It also enforces good action hygiene by using the "[Source] Event" pattern in defining action types.

Resources

Official docs of the createActionGroup function

Peer Reviewers

Thank you friends for reviewing the createActionGroup PR and giving me helpful suggestions on this article!

Building Count-Up Animation with Angular and RxJS

Marko Stanimirović — Tue, 21 Dec 2021 11:20:12 +0000

Cover photo by Andy Holmes on Unsplash.

This article explains how to build a count-up animation in Angular in a reactive way. We are going to build a count-up directive from scratch without third-party libraries. The final result will look like this:

Let's get started!

Generating Directive with Angular CLI

To create a directive in Angular, run the following command:

ng generate directive count-up

The Angular CLI will generate a count-up.directive.ts file that contains an empty directive:

@Directive({
  selector: '[countUp]'
})
export class CountUpDirective {
  constructor() {}
}

Defining Inputs

The CountUpDirective has two inputs: count and animation duration, where the name of the count input is the same as the name of the directive selector. Using the CountUpDirective in the template will look like this:

<p [countUp]="200" [duration]="5000"></p>

These inputs are defined in the CountUpDirective as follows:

@Directive({
  selector: '[countUp]'
})
export class CountUpDirective {
  @Input('countUp') // input name is the same as selector name
  set count(count: number) {}

  @Input()
  set duration(duration: number) {}
}

As you can see, inputs are defined as setters. Input values will be emitted to RxJS subjects, which will allow us to reactively listen to their changes, without using the OnChanges lifecycle hook.

Defining Local State

The CountUpDirective has two local state slices that will be stored in behavior subjects:

@Directive({
  selector: '[countUp]'
})
export class CountUpDirective {
  // default count value is 0
  private readonly count$ = new BehaviorSubject(0);
  // default duration value is 2000 ms
  private readonly duration$ = new BehaviorSubject(2000);
}

New input values will then be emitted to these subjects as inputs change:

@Directive({
  selector: '[countUp]'
})
export class CountUpDirective {
  private readonly count$ = new BehaviorSubject(0);
  private readonly duration$ = new BehaviorSubject(2000);

  @Input('countUp')
  set count(count: number) {
    // emit a new value to the `count$` subject
    this.count$.next(count);
  }

  @Input()
  set duration(duration: number) {
    // emit a new value to the `duration$` subject
    this.duration$.next(duration);
  }
}

The next step is to build the currentCount$ observable that will be used to display the current count in the template.

Calculating Current Count

To calculate the current count we need values of the count$ and duration$ subjects. We will use the combineLatest operator to reset the calculation of the current count each time the count$ or duration$ changes. The next step is to switch the outer observable with an interval that starts with 0, increases current count over time, then slows down, and ends with the count value when the animation duration expires:

private readonly currentCount$ = combineLatest([
  this.count$,
  this.duration$,
]).pipe(
  switchMap(([count, duration]) => {
    // get the time when animation is triggered
    const startTime = animationFrameScheduler.now();

    // use `animationFrameScheduler` for better rendering performance
    return interval(0, animationFrameScheduler).pipe(
      // calculate elapsed time
      map(() => animationFrameScheduler.now() - startTime),
      // calculate progress
      map((elapsedTime) => elapsedTime / duration),
      // complete when progress is greater than 1
      takeWhile((progress) => progress <= 1),
      // apply quadratic ease-out function
      // for faster start and slower end of counting
      map((progress) => progress * (2 - progress)),
      // calculate current count
      map((progress) => Math.round(progress * count)),
      // make sure that last emitted value is count
      endWith(count),
      distinctUntilChanged()
    );
  }),
);

We use animationFrameScheduler instead of the default asyncScheduler for better rendering performance. When the animationFrameScheduler is used with interval, the first argument must be 0. Otherwise, it falls back to the asyncScheduler. In other words, the following implementation of currentCount$ uses asyncScheduler under the hood, although the animationFrameScheduler is passed as a second argument to the interval function:

private readonly currentCount$ = combineLatest([
  this.count$,
  this.duration$,
]).pipe(
  switchMap(([count, animationDuration]) => {
    const frameDuration = 1000 / 60; // 60 frames per second
    const totalFrames = Math.round(animationDuration / frameDuration);

    // interval falls back to `asyncScheduler`
    // because the `frameDuration` is different from 0
    return interval(frameDuration, animationFrameScheduler).pipe(
      // calculate progress
      map((currentFrame) => currentFrame / totalFrames), 
      // complete when progress is greater than 1
      takeWhile((progress) => progress <= 1),
      // apply quadratic ease-out function
      map((progress) => progress * (2 - progress)),
      // calculate current count
      map((progress) => Math.round(progress * count)),
      // make sure that last emitted value is count
      endWith(count),
      distinctUntilChanged()
    );
  })
);

💡 If you're not familiar with the animationFrameScheduler and its advantages for updating the DOM over the asyncScheduler, take a look at the resources section.

Displaying Current Count

To render the current count within the directive's host element, we need an instance of Renderer2 and a reference to the host element. Both can be injected through the constructor. We will also inject the Destroy provider that will help us to unsubscribe from the currentCount$ observable when the CountUpDirective is destroyed:

@Directive({
  selector: '[countUp]',
  // `Destroy` is provided at the directive level
  providers: [Destroy],
})
export class CountUpDirective {
  constructor(
    private readonly elementRef: ElementRef,
    private readonly renderer: Renderer2,
    private readonly destroy$: Destroy
  ) {}
}

💡 Take a look at this article to learn more about Destroy provider.

Then we need to create a method that listens to the currentCount$ changes and displays emitted values within the host element:

private displayCurrentCount(): void {
  this.currentCount$
    .pipe(takeUntil(this.destroy$))
    .subscribe((currentCount) => {
      this.renderer.setProperty(
        this.elementRef.nativeElement,
        'innerHTML',
        currentCount
      );
    });
}

The displayCurrentCount method will be called in the ngOnInit method.

Wrap-Up

The final version of the CountUpDirective looks like this:

/**
 * Quadratic Ease-Out Function: f(x) = x * (2 - x)
 */
const easeOutQuad = (x: number): number => x * (2 - x);

@Directive({
  selector: '[countUp]',
  providers: [Destroy],
})
export class CountUpDirective implements OnInit {
  private readonly count$ = new BehaviorSubject(0);
  private readonly duration$ = new BehaviorSubject(2000);

  private readonly currentCount$ = combineLatest([
    this.count$,
    this.duration$,
  ]).pipe(
    switchMap(([count, duration]) => {
      // get the time when animation is triggered
      const startTime = animationFrameScheduler.now();

      return interval(0, animationFrameScheduler).pipe(
        // calculate elapsed time
        map(() => animationFrameScheduler.now() - startTime),
        // calculate progress
        map((elapsedTime) => elapsedTime / duration),
        // complete when progress is greater than 1
        takeWhile((progress) => progress <= 1),
        // apply quadratic ease-out function
        // for faster start and slower end of counting
        map(easeOutQuad),
        // calculate current count
        map((progress) => Math.round(progress * count)),
        // make sure that last emitted value is count
        endWith(count),
        distinctUntilChanged()
      );
    }),
  );

  @Input('countUp')
  set count(count: number) {
    this.count$.next(count);
  }

  @Input()
  set duration(duration: number) {
    this.duration$.next(duration);
  }

  constructor(
    private readonly elementRef: ElementRef,
    private readonly renderer: Renderer2,
    private readonly destroy$: Destroy
  ) {}

  ngOnInit(): void {
    this.displayCurrentCount();
  }

  private displayCurrentCount(): void {
    this.currentCount$
      .pipe(takeUntil(this.destroy$))
      .subscribe((currentCount) => {
        this.renderer.setProperty(
          this.elementRef.nativeElement,
          'innerHTML',
          currentCount
        );
      });
  }
}

Demo

Resources

Peer Reviewers

Tim Deschryver

Thank you Tim for giving me helpful suggestions on this article!

NgRx Tips I Needed in the Beginning

Marko Stanimirović — Wed, 10 Nov 2021 10:51:06 +0000

Cover photo by Léonard Cotte on Unsplash.

This article contains a list of tips and best practices for using the @ngrx/store and @ngrx/effects libraries. The list is based on the usual NgRx mistakes I've seen many times (some of which I've made myself) and on the great talks and articles that you can find in the resources section.

Store Tips
- Put global state in a single place
- Don't put the local state in the global store
- Use selectors for the derived state
- Use view model selectors
- Treat actions as unique events
- Group actions by source
- Don't dispatch actions conditionally
- Create reusable reducers
- Be careful with facades
Effects Tips
- Name effects like functions
- Keep effects simple
- Don't create "boiler" effects
- Apply single responsibility principle
- Apply good action hygiene
Conclusion
Resources
Peer Reviewers

Store Tips

Put global state in a single place

Try to keep the global state of your application in a single place - NgRx store. Having the state spread across multiple stateful services makes an application harder to maintain. It also frequently leads to these services "re-storing" a derived state, which makes it harder to understand where the actual source of truth for a specific data lives.

However, if you are in the process of migrating your application to NgRx, then it's fine to keep legacy stateful services as a temporary solution.

Don't put the local state in the global store

The local state is tied to the lifecycle of a particular component. It is initialized and managed during the component lifetime and cleaned up when the component is destroyed.

It's completely fine to store the local state in the component and manage it imperatively. However, if you're already using a reactive global state management solution such as NgRx store, then consider using a reactive solution for the local state management such as @ngrx/component-store. It has many powerful features and fits perfectly with the global NgRx store.

Use selectors for the derived state

Don't put the derived state in the store, use selectors instead.

Let's first see the reducer that manages the state with the derived value:

export const musiciansReducer = createReducer(
  on(musiciansPageActions.search, (state, { query }) => {
    // `filteredMusicians` is derived from `musicians` and `query`
    const filteredMusicians = state.musicians.filter(({ name }) =>
      name.includes(query)
    );

    return {
      ...state,
      query,
      filteredMusicians,
    };
  }))
);

The value of filteredMusicians is derived from the query and musicians array. If you decide to keep the derived value in the store, then you should update it every time one of the values from which it is derived changes. The state will be larger, the reducer will contain additional logic, and you can easily forget to add filtering logic in another reducer that updates query or musicians.

The right way to handle the derived state is via selectors. The selector that returns filtered musicians will look like this:

export const selectFilteredMusicians = createSelector(
  selectAllMusicians,
  selectMusicianQuery,
  (musicians, query) =>
    musicians.filter(({ name }) => name.includes(query))
);

And musiciansReducer will now be much simpler:

export const musiciansReducer = createReducer(
  on(musiciansPageActions.search, (state, { query }) => ({
    ...state,
    query,
  }))
);

Use view model selectors

View model selector combines other selectors to return all state chunks required for a particular view. It's a great way to make a container component cleaner by having a single selector per container. Besides that, view model selectors provide additional benefits.

Let's first see what the container component will look like without the view model selector:

@Component({
  // the value of each Observable is unwrapped via `async` pipe
  template: `
    <musician-search [query]="query$ | async"></musician-search>

    <musician-list
      [musicians]="musicians$ | async"
      [activeMusician]="activeMusician$ | async"
    ></musician-list>

    <musician-details
      [musician]="activeMusician$ | async"
    ></musician-details>
  `,
})
export class MusiciansComponent {
  // select all state chunks required for the musicians container
  readonly musicians$ = this.store.select(selectFilteredMusicians);
  readonly query$ = this.store.select(selectMusiciansQuery);
  readonly activeMusician$ = this.store.select(selectActiveMusician);

  constructor(private readonly store: Store) {}
}

There are several drawbacks of this approach:

The size of the container component increases with the number of required state chunks.
Testing is harder - there can be many selectors to mock.
There are multiple subscriptions in the template.

Let's now create a view model selector for this container:

export const selectMusiciansPageViewModel = createSelector(
  selectFilteredMusicians,
  selectMusiciansQuery,
  selectActiveMusician,
  (musicians, query, activeMusician) => ({
    musicians,
    query,
    activeMusician,
  })
);

And the container now looks like this:

@Component({
  // single subscription in the template via `async` pipe
  // access to the view model properties via `vm` alias
  template: `
    <ng-container *ngIf="vm$ | async as vm">
      <musician-search [query]="vm.query"></musician-search>

      <musician-list
        [musicians]="vm.musicians"
        [activeMusician]="vm.activeMusician"
      ></musician-list>

      <musician-details
        [musician]="vm.activeMusician"
      ></musician-details>
    </ng-container>
  `,
})
export class MusiciansComponent {
  // select the view model
  readonly vm$ = this.store.select(selectMusiciansPageViewModel);

  constructor(private readonly store: Store) {}
}

The component is now smaller and easier for testing. Also, there is a single subscription in the template.

Treat actions as unique events

Treat NgRx actions as unique events, not as commands, and don't reuse them.

Commands can be fine for simple and isolated features. However, they can lead to dirty code and imply performance issues for complex functionalities that consume multiple feature states. Let's now walk through the example, to understand the importance of treating actions as unique events (a.k.a. good action hygiene).

There is a straightforward NgRx flow for pages that display a list of entities:

Dispatch the action to load the entity collection on component initialization.
Listen to this action in effect, load entities from the API, and return new action with loaded entities as a payload.
Create a case reducer that will listen to the action returned from the effect and add loaded entities to the state.
Finally, select entities from the store and display them in the template:

@Component(/* ... */)
export class SongsComponent implements OnInit {
  // select songs from the store
  readonly songs$ = this.store.select(selectSongs);

  constructor(private readonly store: Store) {}

  ngOnInit(): void {
    // dispatch the `loadSongs` action on component initialization
    this.store.dispatch({ type: '[Songs] Load Songs' });
  }
}

And this works fine. There is no need to change anything at first. However, what if we want to load another collection that is needed for a particular container component. In this example, imagine that we want to show the composer for each loaded song. If we treat actions as commands, then the ngOnInit method of SongsComponent will look like this:

ngOnInit(): void {
  this.store.dispatch({ type: '[Songs] Load Songs' });
  this.store.dispatch({ type: '[Composers] Load Composers' });
}

Here we come to another very important rule: Don't dispatch multiple actions sequentially. Sequentially dispatched actions can lead to unexpected intermediate states and cause unnecessary event loop cycles.

It would be much better to dispatch single action indicating that the user has opened the songs page, and listen to that action in both loadSongs$ and loadComposers$ effects:

ngOnInit(): void {
  this.store.dispatch({ type: '[Songs Page] Opened' });
}

"Songs Page" is the source of this action (it's dispatched from the songs page) and "Opened" is the name of the event (the songs page is opened).

This brings us to a new rule: Be consistent in naming actions, use "[Source] Event" pattern. Also, be descriptive in naming actions. It could help a lot in application maintenance, especially for catching bugs.

If we check the Redux DevTools for this example when actions are treated as unique events, we'll see something like this:

[Login Page] Login Form Submitted
[Auth API] User Logged in Successfully
[Songs Page] Opened
[Songs API] Songs Loaded Successfully
[Composers API] Composers Loaded Successfully

When we see a list of well-described actions, we can easily conclude what happened in our application:

The user submitted a login form.
Auth API responded that the login was successful.
The user opened the songs page.
Songs successfully loaded from the Song API.
Composers successfully loaded from the Composers API.

Unfortunately, this is not the case with commands:

[Auth] Login
[Auth] Login Success
[Songs] Load Songs
[Composers] Load Composers
[Songs] Load Songs Success
[Composers] Load Composers Success

Commands can be dispatched from multiple places, so we can't figure out what their source is.

Group actions by source

We saw in the previous example that one action can cause changes in multiple feature states. Therefore, do not group actions by feature state, but group them by source.

Create action file per source. Here are some examples of action files grouped by source:

// songs-page.actions.ts
export const opened = createAction('[Songs Page] Opened');
export const searchSongs = createAction(
  '[Songs Page] Search Songs Button Clicked',
  props<{ query: string }>()
);
export const addComposer = createAction(
  '[Songs Page] Add Composer Form Submitted',
  props<{ composer: Composer }>()
);

// songs-api.actions.ts
export const songsLoadedSuccess = createAction(
  '[Songs API] Songs Loaded Successfully',
  props<{ songs: Song[] }>()
);
export const songsLoadedFailure = createAction(
  '[Songs API] Failed to Load Songs',
  props<{ errorMsg: string }>()
);

// composers-api.actions.ts
export const composerAddedSuccess = createAction(
  '[Composers API] Composer Added Successfully',
  props<{ composer: Composer }>()
);
export const composerAddedFailure = createAction(
  '[Composers API] Failed to Add Composer',
  props<{ errorMsg: string }>()
);

// composer-exists-guard.actions.ts
export const canActivate = createAction(
  '[Composer Exists Guard] Can Activate Entered',
  props<{ composerId: string }>()
);

Don't dispatch actions conditionally

Don't dispatch actions conditionally based on the state value. Move the condition to the effect or reducer instead. This tip also relates to good action hygiene.

Let's first look at the case when an action is dispatched based on the state value:

@Component(/* ... */)
export class SongsComponent implements OnInit {
  constructor(private readonly store: Store) {}

  ngOnInit(): void {
    this.store.select(selectSongs).pipe(
      tap((songs) => {
        // if the songs are not loaded
        if (!songs) {
          // then dispatch the `loadSongs` action
          this.store.dispatch(songsActions.loadSongs());
        }
      }),
      take(1)
    ).subscribe();
  }
}

In the example above, the loadSongs action is dispatched if the songs have not already been loaded. However, there is a better way to achieve the same result but to keep the component clean. We can move this condition to the effect:

readonly loadSongsIfNotLoaded$ = createEffect(() => {
  return this.actions$.pipe(
    // when the songs page is opened
    ofType(songsPageActions.opened),
    // then select songs from the store
    concatLatestFrom(() => this.store.select(selectSongs)),
    // and check if the songs are loaded
    filter(([, songs]) => !songs),
    // if not, load songs from the API
    exhaustMap(() => {
      return this.songsService.getSongs().pipe(
        map((songs) => songsApiActions.songsLoadedSuccess({ songs })),
        catchError((error: { message: string }) =>
          of(songsApiActions.songsLoadedFailure({ error }))
        )
      );
    })
  );
});

Then, the component will look much cleaner:

@Component(/* ... */)
export class SongsComponent implements OnInit {
  constructor(private readonly store: Store) {}

  ngOnInit(): void {
    this.store.dispatch(songsPageActions.opened());
  }
}

Create reusable reducers

Use a single case reducer when multiple actions trigger the same state change:

export const composersReducer = createReducer(
  initialState,
  // case reducer can listen to multiple actions
  on(
    composerExistsGuardActions.canActivate,
    composersPageActions.opened,
    songsPageActions.opened,
    (state) => ({ ...state, isLoading: true })
  )
);

However, if any of these actions require a different state change, don't add additional logic to the existing case reducer as follows:

export const composersReducer = createReducer(
  initialState,
  on(
    composerExistsGuardActions.canActivate,
    composersPageActions.opened,
    songsPageActions.opened,
    (state, action) =>
      // `composerExistsGuardActions.canActivate` action requires
      // different state change
      action.type === composerExistsGuardActions.canActivate.type &&
      state.entities[action.composerId]
        ? state
        : { ...state, isLoading: true }
  )
);

Instead, create a new case reducer:

export const composersReducer = createReducer(
  initialState,
  on(
    composersPageActions.opened,
    songsPageActions.opened,
    (state) => ({ ...state, isLoading: true })
  ),
  // `composerExistsGuardActions.canActivate` action is moved
  // to a new case reducer
  on(
    composerExistsGuardActions.canActivate,
    (state, { composerId }) =>
      state.entities[composerId]
        ? state
        : { ...state, isLoading: true }
  )
);

Be careful with facades

I used facades as NgRx store wrappers before, but I stopped, and here are several reasons why:

If the Redux pattern is not your cup of tea and you have a need to wrap it in services, then you should take a look at service-based state management solutions such as Akita or NGXS (or use @ngrx/component-store for the global state as well).
Using facades doesn't make much sense when view model selectors are used and when good action hygiene is applied. You will have an extra layer for testing and maintenance, without any benefit.
Without strict rules in the coding guide, facades leave plenty of space for abuse (e.g. performing side effects).

However, if a container component has a local state but also uses a global state, then consider using the ComponentStore as a dedicated facade for that container. In that case, ComponentStore will manage the local state, but will also select global state slices and/or dispatch actions to the global store.

Effects Tips

Name effects like functions

Name the effects based on what they are doing, not based on the action they are listening to.

If we name the effect based on the action it listens to, it looks like this:

// the name of the effect is the same as the action it listens to
readonly composerAddedSuccess$ = createEffect(
  () => {
    return this.actions$.pipe(
      ofType(composersApiActions.composerAddedSuccess),
      tap(() => this.alert.success('Composer saved successfully!'))
    );
  },
  { dispatch: false }
);

There are at least two drawbacks of this approach. The first is that we cannot conclude what this effect does based on its name. The second is that it is not in accordance with open-closed principle - if we want to trigger the same effect for another action, we should change its name. However, if we name this effect as a function (showSaveComposerSuccessAlert), the previously mentioned drawbacks will be solved.

For example, if we want to display the same success alert when the composer is successfully updated, we only need to pass the composerUpdatedSuccess action to the ofType operator, without having to change the effect name:

// the effect name describes what the effect does
readonly showSaveComposerSuccessAlert$ = createEffect(
  () => {
    return this.actions$.pipe(
      ofType(
        composersApiActions.composerAddedSuccess,
        // new action is added here
        // the rest of the effect remains the same
        composersApiActions.composerUpdatedSuccess
      ),
      tap(() => this.alert.success('Composer saved successfully!'))
    );
  },
  { dispatch: false }
);

Keep effects simple

There are cases when we need to invoke multiple API calls to perform a side effect, or when the format of API response is not appropriate, so we need to restructure it. However, putting all that logic into the NgRx effect can lead to very unreadable code.

Here is an example of an effect that requires two API calls to get all the necessary data:

readonly loadMusician$ = createEffect(() => {
  return this.actions$.pipe(
    // when the musician details page is opened
    ofType(musicianDetailsPage.opened),
    // then select musician id from the route
    concatLatestFrom(() =>
      this.store.select(selectMusicianIdFromRoute)
    ),
    concatMap(([, musicianId]) => {
      // and load musician from the API
      return this.musiciansResource.getMusician(musicianId).pipe(
        // wait for musician to load
        mergeMap((musician) => {
          // then load band from the API
          return this.bandsResource.getBand(musician.bandId).pipe(
            // append band name to the musician
            map((band) => ({ ...musician, bandName: band.name }))
          );
        }),
        // if the musician is successfully loaded
        // then return success action and pass musician as a payload
        map((musician) =>
          musiciansApiActions.musicianLoadedSuccess({ musician })
        ),
        // if an error occurs, then return error action
        catchError((error: { message: string }) =>
          of(musiciansApiActions.musicianLoadedFailure({ error }))
        )
      );
    })
  );
});

This is large and unreadable effect, even with comments. However, we can move API calls to the service and make the effect more readable. The service method for getting the musician will look like this:

@Injectable()
export class MusiciansService {
  getMusician(musicianId: string): Observable<Musician> {
    return this.musiciansResource.getMusician(musicianId).pipe(
      mergeMap((musician) => {
        return this.bandsResource.getBand(musician.bandId).pipe(
          map((band) => ({ ...musician, bandName: band.name }))
        );
      })
    );
  }
}

It can be used from the loadMusician$ effect, but also from other parts of the application. The loadMusician$ effect now looks much more readable:

readonly loadMusician$ = createEffect(() => {
  return this.actions$.pipe(
    ofType(musicianDetailsPage.opened),
    concatLatestFrom(() =>
      this.store.select(selectMusicianIdFromRoute)
    ),
    concatMap(([, musicianId]) => {
      // API calls are moved to the `getMusician` method
      return this.musiciansService.getMusician(musicianId).pipe(
        map((musician) =>
          musiciansApiActions.musicianLoadedSuccess({ musician })
        ),
        catchError((error: { message: string }) =>
          of(musiciansApiActions.musicianLoadedFailure({ error }))
        )
      );
    })
  );
});

If you're working with legacy APIs, you're probably having trouble with an API that doesn't return responses in the format your application needs, so you need to convert them. Apply the same principle described above: move the API call along with the mapping logic to the service method and use it from the effect.

Don't create "boiler" effects

Don't create effects that map multiple related actions into a single action:

// this effect returns the `loadMusicians` action
// when current page or page size is changed
readonly invokeLoadMusicians$ = createEffect(() => {
  return this.actions$.pipe(
    ofType(
      musiciansPageActions.currentPageChanged,
      musiciansPageActions.pageSizeChanged
    ),
    map(() => musiciansActions.loadMusicians())
  );
});

// this effect loads musicians from the API
// when the `loadMusicians` action is dispatched
readonly loadMusicians$ = createEffect(() => {
  return this.actions$.pipe(
    ofType(musiciansAction.loadMusicians),
    concatLatestFrom(() =>
      this.store.select(selectMusiciansPagination)
    ),
    switchMap(([, pagination]) => {
      return this.musiciansService.getMusicians(pagination).pipe(
        /* ... */
      );
    }) 
  );
});

Because the ofType operator can accept a sequence of actions:

readonly loadMusicians$ = createEffect(() => {
  return this.actions$.pipe(
    // `ofType` accepts a sequence of actions
    // and there is no need for "boiler" effects (and actions)
    ofType(
      musiciansPageActions.currentPageChanged,
      musiciansPageActions.pageSizeChanged
    ),
    concatLatestFrom(() =>
      this.store.select(selectMusiciansPagination)
    ),
    switchMap(([, pagination]) => {
      return this.musiciansService.getMusicians(pagination).pipe(
        /* ... */
      );
    }) 
  );
});

Apply single responsibility principle

In other words, don't perform multiple side effects within a single NgRx effect. Effects with single responsibility are more readable and easier to maintain.

Let's first see the NgRx effect that performs two side effects:

readonly deleteSong$ = createEffect(() => {
  return this.actions$.pipe(
    ofType(songsPageActions.deleteSong),
    concatMap(({ songId }) => {
      // side effect 1: delete the song
      return this.songsService.deleteSong(songId).pipe(
        map(() => songsApiActions.songDeletedSuccess({ songId })),
        catchError(({ message }: { message: string }) => {
          // side effect 2: display an error alert in case of failure
          this.alert.error(message);
          return of(songsApiActions.songDeletedFailure({ message }));
        })
      );
    })
  );
});

If we apply the single responsibility principle, we'll have two NgRx effects:

// effect 1: delete the song
readonly deleteSong$ = createEffect(() => {
  return this.actions$.pipe(
    ofType(songsPageActions.deleteSong),
    concatMap(({ songId }) => {
      return this.songsService.deleteSong(songId).pipe(
        map(() => songsApiActions.songDeletedSuccess({ songId })),
        catchError(({ message }: { message: string }) =>
          of(songsApiActions.songDeletedFailure({ message }))
        )
      );
    })
  );
});

// effect 2: show an error alert
readonly showErrorAlert$ = createEffect(
  () => {
    return this.actions$.pipe(
      ofType(songsApiActions.songDeletedFailure),
      tap(({ message }) => this.alert.error(message))
    );
  },
  { dispatch: false }
);

And here is another advantage: Effects with single responsibility are reusable. We can use the showErrorAlert$ effect for any action that requires an error alert to be shown.

Apply good action hygiene

The same principles described for actions that are dispatched via store should be applied to the effects:

Don't return an array of actions (commands) from the effect.
Return unique action that can be handled by multiple reducers and/or effects.

Let's first see an example where multiple actions are returned from the effect:

readonly loadAlbum$ = createEffect(() => {
  return this.actions$.pipe(
    ofType(albumsActions.loadCurrentAlbum),
    concatLatestFrom(() => this.store.select(selectAlbumIdFromRoute)),
    concatMap(([, albumId]) => {
      return this.albumsService.getAlbum(albumId).pipe(
        // an array of actions is returned on successful load
        // then, `loadSongsSuccess` is handled by `songsReducer`
        // and `loadComposersSuccess` is handled by `composersReducer`
        mergeMap(({ songs, composers }) => [
          songsActions.loadSongsSuccess({ songs }),
          composersActions.loadComposersSuccess({ composers }),
        ]),
        catchError(/* ... */)
      );
    })
  );
});

I have seen similar effects many times. This happens when actions are treated as commands. You can see the drawbacks of this approach in the Treat actions as unique events section.

However, if we apply good action hygiene, the loadAlbum$ effect will look like this:

readonly loadAlbum$ = createEffect(() => {
  return this.actions$.pipe(
    // when the album details page is opened
    ofType(albumDetailsPageActions.opened),
    // then select album id from the route
    concatLatestFrom(() => this.store.select(selectAlbumIdFromRoute)),
    concatMap(([, albumId]) => {
      // and load current album from the API
      return this.albumsService.getAlbum(albumId).pipe(
        // return unique action when album is loaded successfully
        map(({ songs, composers }) =>
          albumsApiActions.albumLoadedSuccess({ songs, composers })
        ),
        catchError(/* ... */)
      );
    })
  );
});

Then, the albumLoadedSuccess action can be handled by the reducer(s) and/or other effects. In this example, it will be handled by songsReducer and composersReducer:

// songs.reducer.ts
export const songsReducer = createReducer(
  on(albumsApiActions.albumLoadedSuccess, (state, { songs }) => ({
    ...state,
    songs,
  }))
);

// composers.reducer.ts
export const composersReducer = createReducer(
  on(albumsApiActions.albumLoadedSuccess, (state, { composers }) => ({
    ...state,
    composers,
  }))
);

Conclusion

NgRx provides the ability to implement the same functionality in many different ways. However, some of the ways have emerged over time as best practices and you should consider applying them in your project to increase code quality, performance, and maintainability.

Resources

Good Action Hygiene with NgRx by Mike Ryan
Rethinking State in Angular Applications by Alex Okrushko
Building Sub States with NgRx Selectors by Brandon Roberts
Maximizing and Simplifying Component Views with NgRx Selectors by Brandon Roberts
Solving Angular Slow Renders with NgRx Selectors by Tim Deschryver
Start Using NgRx Effects for This by Tim Deschryver

Peer Reviewers

Big thanks to my teammates Brandon, Tim, and Alex for giving me helpful suggestions on this article!

DRY Way to Manage Subscriptions in Angular Components

Marko Stanimirović — Tue, 28 Sep 2021 12:10:26 +0000

Cover photo by Tim Swaan on Unsplash.

This article explains how to manage subscriptions in Angular components without repeating the same teardown logic in each component.

Common Ways

There are two common ways to manage RxJS subscriptions in Angular components to prevent memory leaks:

Using Subscription

@Component({
  selector: 'interval',
  templateUrl: './interval.component.html',
})
export class IntervalComponent implements OnInit, OnDestroy {
  // initialize `Subscription` object
  private readonly subscriptions = new Subscription();

  ngOnInit(): void {
    // add all subscriptions to it
    this.subscriptions.add(
      interval(1000)
        .pipe(map(i => `== ${i} ==`))
        .subscribe(console.log)
    );

    this.subscriptions.add(
      interval(2000)
        .pipe(map(i => `=== ${i} ===`))
        .subscribe(console.log)
    );
  }

  ngOnDestroy(): void {
    // unsubscribe from all added subscriptions
    // when component is destroyed
    this.subscriptions.unsubscribe();
  }
}

Using Destroy Subject

@Component({
  selector: 'interval',
  templateUrl: './interval.component.html',
})
export class IntervalComponent implements OnInit, OnDestroy {
  // initialize destroy subject
  private readonly destroySubject$ = new Subject<void>();

  ngOnInit(): void {
    interval(1000)
      .pipe(
        map(i => `== ${i} ==`),
        // unsubscribe when destroy subject emits an event
        takeUntil(this.destroySubject$)
      )
      .subscribe(console.log);

    interval(2000)
      .pipe(
        map(i => `=== ${i} ===`),
        takeUntil(this.destroySubject$)
      )
      .subscribe(console.log);
  }

  ngOnDestroy(): void {
    // emit destroy event when component is destroyed
    this.destroySubject$.next();
  }
}

Both solutions have the same drawback: We have to initialize the additional property, and add teardown logic to the ngOnDestroy method. However, there is a better way to manage subscriptions in Angular components.

Solution

We can put the teardown logic in a single place by creating Destroy class that extends the Observable class and implements the OnDestroy interface:

@Injectable()
export class Destroy extends Observable<void> implements OnDestroy {
  // initialize destroy subject
  private readonly destroySubject$ = new ReplaySubject<void>(1);

  constructor() {
    // emit destroy event to all subscribers when destroy subject emits
    super(subscriber => this.destroySubject$.subscribe(subscriber));
  }

  ngOnDestroy(): void {
    // emit destroy event when component that injects
    // `Destroy` provider is destroyed
    this.destroySubject$.next();
    this.destroySubject$.complete();
  }
}

Then, we can provide Destroy at the component level and inject it through the constructor:

@Component({
  // provide `Destroy` at the component level
  viewProviders: [Destroy]
})
export class IntervalComponent implements OnInit {
  // inject it through the constructor
  constructor(private readonly destroy$: Destroy) {}

  ngOnInit(): void {
    interval(1000)
      .pipe(
        map(i => `== ${i} ==`),
        // unsubscribe when `destroy$` Observable emits an event
        takeUntil(this.destroy$)
      )
      .subscribe(console.log);
  }
}

When a provider is provided at the component level, it will be tied to the component lifecycle which allows us to use the ngOnDestroy lifecycle method within it. Therefore, the ngOnDestroy method of the Destroy provider will be called when the IntervalComponent is destroyed.

Conclusion

In general, manual (un)subscriptions in Angular components should be avoided. If you need to perform a side effect at the component level, you can do so using the @ngrx/component-store effects, and let ComponentStore take care to prevent memory leaks. However, if you prefer to manage the side effects in the components, consider using the Destroy provider to avoid repeating the same teardown logic in each component.

Peer Reviewers

NgRx Feature Creator

Marko Stanimirović — Tue, 14 Sep 2021 12:42:02 +0000

Cover photo by Sigmund on Unsplash.

The createFeature function is introduced in NgRx v12.1.
It reduces repetitive code in selector files by generating a feature selector and child selectors for each feature state property. It's inspired by the ngrx-child-selectors library.

NgRx Feature

There are three main building blocks of global state management with @ngrx/store: actions, reducers, and selectors. For a particular feature state, we create a reducer for handling state transitions based on the dispatched actions, and selectors to obtain slices of the feature state. Also, we need to define a feature name needed to register the feature reducer in the NgRx store. Therefore, we can consider the NgRx feature as a grouping of the feature name, feature reducer, and selectors for the particular feature state. Let's now look at the "traditional" way of creating the NgRx feature.

To create a reducer there is the createReducer function from the @ngrx/store package:

// books.reducer.ts
import { createReducer } from "@ngrx/store";

import * as BookListPageActions from "./book-list-page.actions";
import * as BooksApiActions from "./books-api.actions";

export const featureName = "books";

export interface State {
  books: Book[];
  loading: boolean;
}

const initialState: State = {
  books: [],
  loading: false,
};

export const reducer = createReducer(
  initialState,
  on(BookListPageActions.enter, (state) => ({
    ...state,
    loading: true,
  })),
  on(BooksApiActions.loadBooksSuccess, (state, { books }) => ({
    ...state,
    books,
    loading: false,
  }))
);

To register this reducer in the NgRx store, we use the StoreModule.forFeature method:

// books.module.ts
import { StoreModule } from "@ngrx/store";

import * as fromBooks from "./books.reducer";

@NgModule({
  imports: [
    StoreModule.forFeature(fromBooks.featureName, fromBooks.reducer),
  ],
})
export class BooksModule {}

To select the state from the store, let's create a feature selector, child selectors, and also a view model selector:

// books.selectors.ts
import { createFeatureSelector, createSelector } from "@ngrx/store";

import * as fromBooks from "./books.reducer";

// feature selector
export const selectBooksState = createFeatureSelector<fromBooks.State>(
  fromBooks.featureKey
);

// child selectors
export const selectBooks = createSelector(
  selectBooksState,
  (state) => state.books
);
export const selectLoading = createSelector(
  selectBooksState,
  (state) => state.loading
);

// view model selector
export const selectBookListPageViewModel = createSelector(
  selectBooks,
  selectLoading,
  (books, loading) => ({ books, loading })
);

Using Feature Creator

Let's now look at how to achieve the same result by using the createFeature function. We will first refactor the reducer file:

// `createFeature` is imported from `@ngrx/store`
import { createFeature, createReducer } from "@ngrx/store";

import * as BookListPageActions from "./book-list-page.actions";
import * as BooksApiActions from "./books-api.actions";

interface State {
  books: Book[];
  loading: boolean;
}

const initialState: State = {
  books: [],
  loading: false,
};

// feature name and reducer are now passed to `createFeature`
export const booksFeature = createFeature({
  name: "books",
  reducer: createReducer(
    initialState,
    on(BookListPageActions.enter, (state) => ({
      ...state,
      loading: true,
    })),
    on(BooksApiActions.loadBooksSuccess, (state, { books }) => ({
      ...state,
      books,
      loading: false,
    }))
  ),
});

Registering the feature reducer in the store can now be done by passing the entire feature object to the StoreModule.forFeature method:

// books.module.ts
import { StoreModule } from "@ngrx/store";
import { booksFeature } from "./books.reducer";

@NgModule({
  imports: [StoreModule.forFeature(booksFeature)],
})
export class BooksModule {}

Finally, let's see what the selector file looks like:

// books.selectors.ts
import { createSelector } from "@ngrx/store";
import { booksFeature } from "./books.reducer";

export const selectBookListPageViewModel = createSelector(
  booksFeature.selectBooks,
  booksFeature.selectLoading,
  (books, loading) => ({ books, loading })
);

The previously manually created feature and child selectors are now removed because createFeature generates them for us. All generated selectors have the "select" prefix and the feature selector has the "State" suffix.

In this example, the name of the feature selector is selectBooksState, where "books" is the feature name. The names of the child selectors are selectBooks and selectLoading, based on the property names of the books feature state.

Conclusion

Feature creators reduce repetitive code in selector files by using the power of template literal types introduced in TypeScript v4.1. It could bring big improvements to your code, especially with huge feature states.

Resources

Official docs of the createFeature function

Peer Reviewers

Tim Deschryver

Thank you Tim for giving me helpful suggestions on this article!

The "NgRx Feature Creator" guide is now available in the official NgRx documentation. Read more here.

Forem: Marko Stanimirović

Announcing Events Plugin for NgRx SignalStore: A Modern Take on Flux Architecture

Experimental Stage 🚧

Flux Architecture 🔄

Walkthrough 🛠️

Defining Events

Performing State Changes

Performing Side Effects

Reading State

Dispatching Events

Scaling Up

Key Takeaways 🔑

Upcoming NgRx Workshops 🎓

Thanks to All Our Contributors and Sponsors! 🏆

Sponsor NgRx 🤝

Announcing NgRx Signals v18: State Encapsulation, Private Store Members, Enhanced Entity Management, and more!

NgRx Signals Are Now Stable! 🎉

State Encapsulation 🔒

Ensuring Integrity of Store Members 👨‍⚕️

Private Store Members 🛡️

State Tracking 🕵

Enhanced Entity Management 🧩

selectId

entityConfig

Upgrading to NgRx Signals 18 🛠️

Upcoming NgRx Workshops 🎓

Welcoming New Additions to the NgRx Team 💪

Thanks to All Our Contributors and Sponsors! 🏆

Sponsor NgRx 🤝

Announcing NgRx v16: Integration with Angular Signals, Functional Effects, Standalone Schematics, and more!

NgRx 🤝 Signals

Functional Effects 🔥

Feature Creator Enhancements 🤩

Action Group Creator Improvements 👌

Enhanced Schematics and Standalone Support 🚀

Simplified View Model Selectors 🪄

New tapResponse Signature 😎

Standalone Component APIs 😍

New Router Selector 🤘

NgRx SignalStore 💡

Deprecations and Breaking Changes 💥

Upgrading to NgRx 16 🗓️

Enterprise Support 👨‍🏫

Swag Store and Discord Server 🦺

Contributing to NgRx 🥰

Thanks to all our contributors and sponsors!

Sponsor NgRx 💰

Building Reactive Angular Templates with NgRx Component

Installation

Push Pipe

Let Directive

Tracking Different Observable Events

Combining Multiple Observables

Using Suspense Template

Using Aliases for Non-Observable Values

Summary

Resources

Peer Reviewers

Using NgRx Packages with Standalone Angular Features

Contents

Standalone Angular APIs

Creating Standalone Components

Interop with Angular Modules

Configuring Angular Router

Angular Modules from NgRx Packages

Using NgRx Modules with Standalone Angular APIs

Standalone NgRx APIs

Source Code

Resources

Peer Reviewers

NgRx Action Group Creator

Using Action Creator

Using Action Group Creator

Limitations

Conclusion

Resources

Peer Reviewers

Building Count-Up Animation with Angular and RxJS

Generating Directive with Angular CLI

Defining Inputs

`selectId`

`entityConfig`