NgRx Tips I Needed in the Beginning

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.

Contents

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 addComposerSuccess$ = 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.changeCurrentPage,
      musiciansPageActions.changePageSize
    ),
    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.changeCurrentPage,
      musiciansPageActions.changePageSize
    ),
    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.deleteSongFailure),
      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

Alex Okrushko

Tim Deschryver

Brandon Roberts

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