npm:ngrx-rtk-query

README

ngrx-rtk-query is a plugin to make RTK Query (including auto-generated hooks) works in Angular applications with NgRx!! Mix the power of RTK Query + NgRx + RxJS to achieve the same functionality as in the RTK Query guide with hooks.

Installation
Basic Usage
Usage
FAQ

Installation

⚠️ ngrx-rtk-query library requires TypeScript 4.1 or higher.

You can install it through Angular CLI:

ng add ngrx-rtk-query

or with npm:

npm install ngrx-rtk-query

When you install using npm or yarn, you will also need to import StoreRtkQueryModule in your app.module. You can also set setupListeners here.:

import { StoreRtkQueryModule } from 'ngrx-rtk-query';

@NgModule({
  imports: [
    ... // NgRx Modules here!!
    StoreRtkQueryModule.forRoot({ setupListeners: true })
  ],
})
class AppModule {}

Basic Usage

You can follow the official RTK Query guide with hooks, with slight variations.

You can see the application of this repository for more examples.

First, you need to install redux-toolkit:

npm install @reduxjs/toolkit

We'll create a service definition that queries the publicly available

import { fetchBaseQuery } from '@reduxjs/toolkit/query';
import { createApi } from 'ngrx-rtk-query';

export interface CountResponse {
  count: number;
}

export const counterApi = createApi({
  reducerPath: 'counterApi',
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  tagTypes: ['Counter'],
  endpoints: (build) => ({
    getCount: build.query<CountResponse, void>({
      query: () => ({
        url: `count`,
      }),
      providesTags: ['Counter'],
    }),
    incrementCount: build.mutation<CountResponse, number>({
      query: (amount) => ({
        url: `increment`,
        method: 'PUT',
        body: { amount },
      }),
      invalidatesTags: ['Counter'],
    }),
    decrementCount: build.mutation<CountResponse, number>({
      query: (amount) => ({
        url: `decrement`,
        method: 'PUT',
        body: { amount },
      }),
      invalidatesTags: ['Counter'],
    }),
  }),
});

export const {
  useGetCountQuery,
  useIncrementCountMutation,
  useDecrementCountMutation,
} = counterApi;

Add the service to your store

export const reducers: ActionReducerMap<RootState> = {
  [counterApi.reducerPath]: counterApi.reducer,
};

@NgModule({
  imports: [
    StoreModule.forRoot(reducers, {
      metaReducers: [counterApi.metareducer],
    }),
    StoreRtkQueryModule.forRoot({ setupListeners: true }),

    !environment.production ? StoreDevtoolsModule.instrument() : [],
  ],
})
export class CoreStoreModule {}

Use the query in a component

import { useDecrementCountMutation, useGetCountQuery, useIncrementCountMutation } from '@app/core/services';

@Component({
  selector: 'app-counter-manager',
  template: `
    <section>
      <button
        *ngIf="increment.state$ | async as incrementState"
        [disabled]="incrementState.isLoading"
        (click)="increment.dispatch(1)"
      > + </button>

      <span *ngIf="countQuery$ | async as countQuery">{{ countQuery.data?.count || 0 }}</span>

      <button
        *ngIf="decrement.state$ | async as decrementState"
        [disabled]="decrementState.isLoading"
        (click)="decrement.dispatch(1)"
      > - </button>
    </section>
  `,
})
export class CounterManagerComponent {
  countQuery$ = useGetCountQuery();
  increment = useIncrementCountMutation();
  decrement = useDecrementCountMutation();
}

Usage

Use on code-splitted/feature/lazy modules

To introduce a lazy/feature/code-splitted query, you must export it through an angular module. Import this module where needed. You can look at posts feature example from this repository.

// ...

export const postsApi = createApi({
  reducerPath: 'postsApi',
  baseQuery: baseQueryWithRetry,
  tagTypes: ['Posts'],
  endpoints: (build) => ({
    // ...
  }),
});

// ...

@NgModule({
  imports: [StoreModule.forFeature(postsApi.reducerPath, postsApi.reducer, { metaReducers: [postsApi.metareducer] })],
})
export class PostsQueryModule {}

Queries

The use of queries is a bit different compared to the original Queries - RTK Query guide. You can look at the examples from this repository.

The parameters and options of the Query can be static or Observables.

The hook useXXXQuery() returns an observable with all the information indicated in the official documentation (including refetch() function). By subscribing to this query (with the async pipe or subscribe()), the query will start its request.

// Use query without params or options
postsQuery$ = useGetPostsQuery();

// Use query with static params or options
postQuery$ = useGetPostsQuery(2, {
  selectFromResult: ({ data: post, isLoading }) => ({ post, isLoading }),
});

// Use query with Observables params or options (can be mixed with static)
postQuery$ = useGetPostsQuery(id$, options$);

Lazy Queries

The use of lazy queries is a bit different compared to the original. As in the case of queries, the parameters and options of the Query can be static or Observables. You can look at lazy feature example from this repository.

Like in the original library, a lazy returns a object (not array) of 3 items, but the structure and naming of the items is different.

fetch(arg): This function is the trigger to run the fetch action.
state$: Observable that returns an object with the query state.
lastArg$: Observable that returns the last argument.

// Use query without options
postsQuery = useLazyGetPostsQuery();
// Use query with static options
postQuery = useLazyGetPostsQuery({
  selectFromResult: ({ data: post, isLoading }) => ({ post, isLoading }),
});
// Use query with Observable options
postQuery = useLazyGetPostsQuery(options$);

Use when data needs to be loaded on demand

<span *ngIf="xxxQuery.state$ | async as xxxQuery">{{ xxxQuery.data }}</span>
<span>{{ xxxQuery.lastArg$ | async }}</span>

//...

export class XxxComponent {
  xxxQuery = useLazyGetXxxQuery();

// ...

  xxx(id: string) {
    this.xxxQuery.fetch(id);
  }

// ...

Another good use case is to work with nested or relational data

<ng-container *ngIf="locationQuery.state$ | async as locationQuery">
//...
</ng-container>

export class CharacterCardComponent implements OnInit {
  @Input() character: Character;

  locationQuery = useLazyGetLocationQuery();

  ngOnInit(): void {
    this.locationQuery.fetch(this.character.currentLocation, { preferCacheValue: true });
  }

// ...

preferCacheValue is false by default. When true, if the request exists in cache, it will not be dispatched again. Perfect for ngOnInit cases. You can look at pagination feature example from this repository.

Mutations

The use of mutations is a bit different compared to the original Mutations - RTK Query guide. You can look at the examples from this repository.

Like in the original library, a mutation is a object (not array) of 2 items, but the structure and naming of the items is different.

dispatch(params): This function is the trigger to run the mutation action.
state$: Observable that returns an object with the state, including the status flags and other info (see official docs).

// Use mutation hook
addPost = useAddPostMutation();

// Mutation trigger
addPost.dispatch({params});
// Observable with the state of mutation
addPost.state$