Thanks @AlexOkrushko and @Nartc1410 for the great feedback.
Managing the state of your Angular application has always been a challenge.
In this tutorial, I will explain how to manage your components' state with @ngrx/component-store
. You will be able to do it in a more organized way and minimizing bugs and UI inconsistencies.
Table of content
- Prerequisites
- What are we going to build?
- What is the "state"?
- Not all Angular apps need NgRx or NGSX
- The problem
- The solution: @ngrx/component-store
- Getting started
Prerequisites
- Basic knowledge of Angular
- Basic knowledge of RXJS
- angular-cli installed or Stackblitz account
What are we going to build?
An application to manage car parking and will have the following parts:
-
store.service
: Where we will manage all our state and all the logic of the UI -
parking-lot.service
: To communicate with the backend (for the demo) -
app.component
: Parent component. We consume the state and add cars to the parking lot -
car-list.component
: To show the list of parked cars
If you wish, you can jump to source code, without obligation 🤓 or directly to the tutorial.
What is the "state"?
It is the representation of your UI using an object, and we could change it in different ways, for example:
- Networks request
- User events
- Changes in the router
- Among others
Example:
state = {
cars: [],
loading: true,
error: '',
}
- List of cars in the parking lot:
cars: []
- To change the UI of our app while doing an operation that takes time to resolve, for example, a network request:
loading: true
- To show errors that may occur during the execution of the application:
error: ''
Almost all components have a state. We handle them indirectly by using properties and changing them during their life cycle.
In short a state is:
- It is an object that represents the view of your component
- It is not the data that comes from the server, in fact, this may be part of it
- It can have as many levels as you need
- It is immutable. When you need to update a property, you don’t change it directly but create a new object with the modified property.
Not all Angular apps need NgRx or NGSX
Most Angular applications do not need a full-blown state management system. It is best to manage the state at the component level before implementing a more complex app-level solution like NgRx or NGSX.
The problem
If you have a smart component with several child components, you probably have many properties in your parent component that you need to pass to the child components.
For sure, your child’s components emit events that will change the properties in its parent.
Keep all these changes in order and under control can become a tedious task because the properties change in many places that can be hard to track, especially in async tasks.
The solution: @ngrx /component-store
The same NgRx team developed @ngrx/component-store. A service based on ReplaySubject
can extend to a service and be consumed by a component.
It allows you to keep all the business logic outside the component (or components) and only subscribes to the state and updates the UI when it changes.
The service you create by extending ComponentStore is unique to a particular component and its children and should be injected directly into the component’s providers
property.
When to use an @ngrx /store or @ngrx /component-store?
In your application, you can use both. Both libraries complement each other.
- If the state needs to persist when you change the URL, that state goes in your global state
- If the state needs to be clean up when you change the URL that goes in your component store
More information in Comparison of ComponentStore and Store.
My recommendation
If you don't have any state management in your app and want to start with one, I recommend starting with @ngrx/component-store
and evaluating if you need something more complicated in the future.
In this way, you can start implementing state management in parts of your app and scale efficiently.
@ngrx /component-store concepts
It has only three very simple concepts that you have to learn:
- Selectors: You select and subscribe to the state, either all or parts of it
- Updater: To update the state. It can be parts or in whole
- Effects: It is also to update the state but do some other necessary task beforehand. For example, an HTTP request to an API
Getting started
The application will have a UI with three sections:
- Form to add the cart
- Table with parked cars
- Error messages
Initializing the application
The first step is to create a new Angular application. With angular-cli. Open a terminal, run the command:
ng new parking-lot-app
We start the application that we created:
cd parking-lot-app
ng serve
Then point your browser to http://localhost:4200/, and you will see your Angular application running with all the information by default.
Creating utilities
The first thing you are going to create is the "Car" interface. You run the command:
ng g interface models/car
Open the file app/models/car.ts
and add:
export interface Car {
plate: string
brand: string
model: string
color: string
}
The above is the very basic model of the car.
Then you create a service that will communicate with the "backend" (only for the demo). You run the command:
ng g service services/parking-lot
Open the file app/services/parking-lot.service.ts
and add:
import { Injectable } from '@angular/core'
import { Observable, of, throwError } from 'rxjs'
import { delay } from 'rxjs/operators'
import { Car } from '../models/car'
const data: Car[] = [
{
plate: '2FMDK3',
brand: 'Volvo',
model: '960',
color: 'Violet',
},
{
plate: '1GYS4C',
brand: 'Saab',
model: '9-3',
color: 'Purple',
},
{
plate: '1GKS1E',
brand: 'Ford',
model: 'Ranger',
color: 'Indigo',
},
{
plate: '1G6AS5',
brand: 'Volkswagen',
model: 'Golf',
color: 'Aquamarine',
},
]
const FAKE_DELAY = 600
@Injectable({
providedIn: 'root',
})
export class ParkingLotService {
private cars: Car[] = []
constructor() {}
add(plate: string): Observable<Car> {
try {
const existingCar = this.cars.find((eCar: Car) => eCar.plate === plate)
if (existingCar) {
throw `This car with plate ${plate} is already parked`
}
const car = this.getCarByPlate(plate)
this.cars = [...this.cars, car]
return of(car).pipe(delay(FAKE_DELAY))
} catch (error) {
return throwError(error)
}
}
private getCarByPlate(plate: string): Car {
const car = data.find((item: Car) => item.plate === plate)
if (car) {
return car
}
throw `The car with plate ${plate} is not register`
}
}
data
: A list of the cars registered in our system. It will act as your car database for the demo.
FAKE_DELAY
: To simulate a small delay to the API request using thedelay
operator from rxjs
Methods:
add
: which receives the vehicle license plate and if it exists adds it to the list of parked cars and if it does not return an error.
getCarByPlate
: this private method only searches our "database" (data
) for the car using the plate, and if it does not exist, it throws an error.
Properties:
car
: To keep track of the cars parked in the "backend".
Defining the state
To define the state, let’s see the application requirements:
- User will add cars by license plate (a request to an API)
- You must indicate to the user the errors:
- The vehicle plate does not exist in the API
- The vehicle is already parked
- You must show indicators in the UI when a request is happening
- Loading: change the button text while the request happening
- Disable: the button and the text field while the request happening
- Show the error when it occurs
Based on these requirements, the state of your UI would be as follows:
interface State {
cars: Car[]
loading: boolean
error: string
}
- A list of parked cars
- A
boolean
for when the app is making a request - A
string
for error messages
Install @ngrx /component-store
To add @ngrx/component-store
to your app use npm
:
npm install @ngrx/component-store --save
Creating the store service
Create the file: app/store.service.ts
and add the following code:
import { Injectable } from '@angular/core'
import { ComponentStore } from '@ngrx/component-store'
import { Car } from './models/car'
// The state model
interface ParkingState {
cars: Car[] // render the table with cars
error: string // show the error when try to add cars
loading: boolean // used to enable/disable elements in the UI while fetching data
}
@Injectable()
export class StoreService extends ComponentStore<ParkingState> {
constructor() {
super({
cars: [],
error: '',
loading: false,
})
}
}
This code is the base of your StoreService
:
- You imported
Injectable
(like any other service) andComponentStore
- You created a
ParkingState
interface that defines the state of your component - You created the
StoreService
class that extends fromComponentStore
and pass the interface - You initialized the UI state through the constructor makes the state immediately available to the
ComponentStore
consumers.
Now you are going to add the rest of the code, selects, updaters and effects. Your service code would be:
import { Injectable } from '@angular/core'
import { ComponentStore } from '@ngrx/component-store'
import { EMPTY, Observable } from 'rxjs'
import { catchError, concatMap, finalize, tap } from 'rxjs/operators'
import { Car } from './models/car'
import { ParkingLotService } from './services/parking-lot.service'
// The state model
interface ParkingState {
cars: Car[] // render the table with cars
error: string // show the error when try to add cars
loading: boolean // used to enable/disable elements in the UI while fetching data
}
@Injectable()
export class StoreService extends ComponentStore<ParkingState> {
constructor(private parkingLotService: ParkingLotService) {
super({
cars: [],
error: '',
loading: false,
})
}
// SELECTORS
readonly vm$: Observable<ParkingState> = this.select((state) => state)
// UPDATERS
readonly updateError = this.updater((state: ParkingState, error: string) => {
return {
...state,
error,
}
})
readonly setLoading = this.updater((state: ParkingState, loading: boolean) => {
return {
...state,
loading,
}
})
readonly updateCars = this.updater((state: ParkingState, car: Car) => {
return {
...state,
error: '',
cars: [...state.cars, car],
}
})
// EFFECTS
readonly = this.effect((plate$: Observable<string>) => {
return plate$.pipe(
concatMap((plate: string) => {
this.setLoading(true)
return this.parkingLotService.add(plate).pipe(
tap({
next: (car) => this.updateCars(car),
error: (e) => this.updateError(e),
}),
finalize(() => {
this.setLoading(false)
}),
catchError(() => EMPTY)
)
})
)
})
}
It’s quite a bit of code, so I will explain it to you in parts and start with the selectors.
Selectors
To create a selector, the select
method is used as follows:
readonly vm$: Observable<ParkingState> = this.select(state => state);
The select
method expects a function that receives the full state. With this state, we can return to the components what is needed; in this case, it returns the entire state.
In this app, you need a selector, but you can have more than one.
Updaters
To update the state, you will need three updaters:
- To add or remove the error message
- To update the loading
- To add cars to the parking lot
To create updaters, use the update
method provided by the ComponentStore
class.
The method receives a function with two parameters, the first is the current state, and the second is the payload the component sent to update the state. This method only has to return the new state.
Error y loading
readonly updateError = this.updater((state: ParkingState, error: string) => {
return {
...state,
error
};
});
readonly setLoading = this.updater(
(state: ParkingState, loading: boolean) => {
return {
...state,
loading
};
}
);
The updateError
receives the error message and use the spread operator to combine with the old state and return the new state.
The setLoading
works the same as the previous one but with the loading
property.
Add cars to parking
This updater receives a car and just adds it to the cars array using the spread operator.
readonly updateCars = this.updater((state: ParkingState, car: Car) => {
return {
...state,
error: '',
cars: [...state.cars, car],
};
});
IMPORTANT: When you update the state, you don't mutate the object (changing some property directly) but return a new object always.
Effects
To add a car to the parking lot, you have to create an effect
because you have to make a request to an API with the car’s license plate, and when it responds, the state is updated.
We use the effect
method that receives a callback with the value that we pass as an Observable to create effects. Keep in mind that each new call of the effect would push the value into that Observable.
readonly addCarToParkingLot = this.effect((plate$: Observable<string>) => {
return plate$.pipe(
concatMap((plate: string) => {
this.setLoading(true);
return this.parkingLotService.add(plate).pipe(
tap({
next: car => this.updateCars(car),
error: e => this.updateError(e)
}),
finalize(() => {
this.setLoading(false);
}),
catchError(() => EMPTY)
);
})
);
});
In this code, you can see that the effect
:
- Receive the car license plate as an
Observable
- Update the state of
loading
- Request the API to add the car to the parking lot using the
ParkingLotService
. - When the request is successful, update the state again: remove the loading and add the cart to the state.
- If it fails: remove the loading and update the state with the error coming from the “backend”
Using concatMap
so that if the effect
gets called multiple times before the call ends, it will resolve all the calls. This RxJS operator will wait until the previous request completes to do the next one.
The tap
operator to handle the case of success and error.
And the catchError
to handle potential errors within the internal pipe.
Creating the <car-list>
component
Run the following command to generate the component.
ng g component components/car-list
In the components/car-list.component.ts
file, add the following code:
import { Component, Input } from '@angular/core'
import { Car } from '../../models/car'
@Component({
selector: 'app-car-list',
templateUrl: './car-list.component.html',
styleUrls: ['./car-list.component.css'],
providers: [],
})
export class CarListComponent {
@Input() cars: Car[] = []
constructor() {}
}
In the components/car-list.component.html
file, add the following code:
<table *ngIf="cars.length; else noCars">
<tr>
<th>Plate</th>
<th>Brand</th>
<th>Model</th>
<th>Color</th>
</tr>
<ng-template ngFor let-car [ngForOf]="cars" let-i="index">
<tr>
<td>{{car.plate}}</td>
<td>{{car.brand}}</td>
<td>{{car.model}}</td>
<td>{{car.color}}</td>
</tr>
</ng-template>
</table>
<ng-template #noCars>
<p>No cars in the parking lot</p>
</ng-template>
In the components/car-list.component.css
we make the table looks fancy:
table {
width: 100%;
border-collapse: collapse;
}
td,
th {
border: solid 1px lightgray;
padding: 0.5rem;
text-align: left;
width: 25%;
}
th {
border-bottom-width: 3px;
}
p {
text-align: center;
}
Finally, make sure that the car-list
component is added to the module.
Open the app/app.module.ts
file, look into the declarations
array, and if it is not there, you can add the CarListComponent
class manually.
Adding the FormModule
As you are going to have a small form with [(ngModel)]
in the app.component
, you must add the FormModule
to the app.module
Open the app/app.module.ts
file and add theFormsModule
to the imports
array. The final code looks like this:
import { BrowserModule } from '@angular/platform-browser'
import { NgModule } from '@angular/core'
import { AppComponent } from './app.component'
import { CarListComponent } from './components/car-list/car-list.component'
import { FormsModule } from '@angular/forms'
@NgModule({
declarations: [AppComponent, CarListComponent],
imports: [BrowserModule, FormsModule],
bootstrap: [AppComponent],
})
export class AppModule {}
Consuming the store service
You created the service specifically for the app.component
and its children.
app/app.component.ts
Add replace all the code with:
import { Component } from '@angular/core'
import { StoreService } from './store.service'
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css'],
providers: [StoreService],
})
export class AppComponent {
plate = ''
vm$ = this.store.vm$
constructor(private store: StoreService) {}
onSubmit($event: Event) {
$event.preventDefault()
this.store.addCarToParkingLot(this.plate)
}
addPlate($event: Event) {
const target = $event.target as HTMLButtonElement
if (target.nodeName === 'BUTTON') {
this.plate = target.innerHTML
}
}
}
StoreService
handles all the business logic, which results in a tiny component. Let’s see the code part by part:
Providers
providers: [StoreService]
: You inject the service at the component level so that this instance only has this component and its children.
Properties
plate
: For the form model, the user will enter the car plate to add to the parking lot.
vm$
It is the observable state from our StoreService
and is updated every time the state changes. We will subscribe to this in the HTML in the next step.
Methods
constructor(private store: StoreService) {}
: You inject the StoreService
into the constructor, just like a regular service.
onSubmit()
: You call it when the form is submitted, and the only thing it does is call the store method addCarToParkingLot
(effect) with the car plate entered by the user in the form.
addPlate()
: This method is not necessary, but for demo purposes, I added it to enter some plates by clicking on some buttons.
app/app.component.html
Add replace all the code with:
<header>
<h1>Parking Lot Control</h1>
</header>
<ng-container *ngIf="vm$ | async as vm">
<div class="messages">
<p class="error" *ngIf="vm.error">{{vm.error}}</p>
</div>
<div class="box">
<form (submit)="onSubmit($event)">
<input
type="text"
[(ngModel)]="plate"
[ngModelOptions]="{standalone: true}"
placeholder="Ex: 2FMDK3, 1GYS4C, 1GKS1E,1G6AS5"
[disabled]="vm.loading"
/>
<button type="submit" [disabled]="vm.loading || !plate.length">
<ng-container *ngIf="vm.loading; else NotLoading">
Loading...
</ng-container>
<ng-template #NotLoading>
Add Car
</ng-template>
</button>
</form>
<div class="shortcuts">
<h5>Shortcuts</h5>
<p (click)="addPlate($event)" class="examples">
<button>2FMDK3</button>
<button>1GYS4C</button>
<button>1GKS1E</button>
<button>1G6AS5</button>
</p>
</div>
</div>
<app-car-list [cars]="vm.cars"></app-car-list>
</ng-container>
<ng-container *ngIf="vm$ | async as vm">
: The first thing is to obtain the ViewModel of the vm$
property that we created in the component class, we use async
pipe to subscribe, and we make a static variable vm
that the rest of our HTML will be able to use.
Error message
The error is a string
, so we just have to show it in the HTML and using interpolation:
<p class="error" *ngIf="vm.error">{{vm.error}}</p>
Form
We create a form for the user to enter the car's plate that they want to add to the parking lot, and we bind the onSubmit
event.
<form (submit)="onSubmit()">
It is a small form with a textfield for the user to enter the plate and a button to execute the add action.
<input>
: Enable/disable based on the state's loading
property.
<button>
: It is enabled/disabled with the loading
property of the state but also if the plate
property of the component is empty (it prevents an empty string
from being sent to the store service)
In the onSubmit
method of the component, we call the effect with the plate number entered by the user, and this is where our ComponentStore service does everything.
app/app.component.css
We add some styles to make our app very good-looking:
h1 {
margin-bottom: 0;
}
.box {
border: solid 1px lightgrey;
padding: 1rem;
display: flex;
justify-content: space-between;
margin-bottom: 1rem;
}
.box p {
margin: 0;
}
.box form {
display: flex;
}
.box form input {
margin-right: 0.5rem;
}
.box form button {
width: 80px;
}
.messages {
height: 2.4rem;
margin: 1rem 0;
}
.messages p {
border: solid 1px transparent;
margin: 0;
padding: 0.5rem;
}
.messages .error {
background-color: lightyellow;
border: solid 1px red;
color: red;
text-align: center;
}
.examples button {
border: 0;
background: none;
color: blue;
text-decoration: underline;
cursor: pointer;
padding: 0;
margin: 0 0.5rem 0 0;
}
.examples button:last-child {
margin: 0;
}
.shortcuts h5 {
margin: 0;
}
.code {
margin-top: 3rem;
border: solid 1px lightgray;
padding: 1rem;
}
.code h4 {
margin: 0 0 1rem;
}
.code pre {
margin: 0;
}
And in the global style file src/styles.css
:
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial,
sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
margin: 3rem;
}
That's it
Go to your browser: https://localhost:4200 and see your app working.
Summary
- You created a service that communicates with the API:
ParkingLotService
- You created a service that handles all the logic and state of the
StoreService
component that extendsComponentStore
- Your UI subscribes to the state of
StoreService
, and every time it changes, your UI is updated.
Using this approach, you will end up with a single “source of truth” for your UI, easy to use without having to change code in many places to update or improve.
Conclusion
As you could see, it is better to start managing the state at the component level before jumping to a complete architecture.
A state is simply an object representing how your interface looks like, and using @ngrx/component-store
and its three basic concepts: select
,update
and effect
, you can handle it in a simple, direct, and more painless way test.
I hope this tutorial has been beneficial for you, and if you have any questions, you can write to me on Twitter by @fmontes.
Top comments (0)