This guide aims to help you become familiar with the Aurelia Store plugin, a means of managing state in your Aurelia applications.

When should you use state management?

Before we delve too deeply into Aurelia Store and how it can help manage the state in your Aurelia applications, we should discuss when to use state management and when not to.

• When you need to reuse data in other parts of your application — State management shines when it comes to helping keep your data organized for cross-application reuse.

• When dealing with complex data structures — An ephermal state is great for simple use cases. Still, when working with complex data structures (think multi-step forms or deeply structured data), state management can help keep it consistent.

• For apps that require the ability to undo or replay data — Because Javascript passes everything by default, passing objects and modifying them can cause complications, especially if you need to undo changes made to an object or redo them. Aurelia Store can help you implement undo/redo functionality.

• For debugging — State management is exceptionally helpful when you want to see what is happening with your data. Mutating objects directly leaves no trail, so they are fragile and hard to debug. You can see what data is being mutated through your actions in the Redux Inspector extension for your browser.

Aurelia Store guides

Please visit one or more of the following sections to learn about the Aurelia Store plugin. If you want to know how to install and configure it, head to the Configuration and setup page first.

Installing Aurelia Store

To install the Aurelia Store plugin, open up a Command Prompt/Terminal and install it:

npm i @aurelia/store-v1

Setup the initial state

When registering the Aurelia Store plugin, you need to pass in the initial state of your application. This is an object which defines the data structure of your application, it needs to be done upfront so the plugin can watch it and act accordingly when it changes.

Create a new file in the src directory called initialstate.ts with your state object inside:

export const initialState = {
    name: '',
    age: '',
    pets: [],
    siteEnabled: true
};

As you can see, it's just a plain old Javascript object. In your application, your properties would be called something different, but you can see we have a mixture of empty values as well as some defaults.

Configuration

To use the Aurelia Store plugin in Aurelia, it needs to be imported and registered. Inside of main.ts the plugin can be registered as follows:

import Aurelia from 'aurelia';
import { StoreConfiguration } from '@aurelia/store-v1';

import { initialState } from './initialstate'; 

Aurelia
  .register(
    StoreConfiguration.withInitialState(initialState)
  )
  .app(MyApp)
  .start();

We import the StoreConfiguration object from the plugin and then called withInitialState which we then pass the state object for your application (we showed you how to do this in the previous step).

Middleware act as an intermediary step in your application to allow you to modify data in your store actions, before and after they have run. Think of middleware as a way to change data after an action has fired.

The Aurelia Store plugin comes with a couple of middleware out of the box for you to use, but you can easily create your own.