Wednesday, 30 November, 2016 UTC
Summary
Nowadays, when developing a web app, a lot of focus is placed on state containers — particularly on all sorts of Flux patterns. One of the most prominent implementations of Flux is Redux . For those of you who haven't caught the hype train yet, Redux is a library that helps you to keep state mutations predictable. It stores the entire state of your application in a single object tree.
In this article, we're going to cover the basics of how to use Redux with Aurelia — a next generation open-source JavaScript client framework. But rather than build yet another counter example, we're going to do something more interesting. We're going to build a simple markdown editor with undo and redo functionality. The code for this tutorial is available on GitHub and there is a demo of the finished project here.
Note: When learning something new, I prefer to go back to the source and in the case of Redux, there is this awesome Egghead Video series by the Redux creator (Dan Abramov). Since we won't go into detail on the way Redux works, if you're in need of a refresher, and have a couple of hours to spare, I can highly recommend giving the series a shot.
How this Tutorial is Structured
In this article, I'm going to build three versions of the same component.
The first version will use a pure Aurelia approach. Here you will learn how to setup an Aurelia app, configure the dependencies and create the necessary View and ViewModel. We will look into building the example the classic Aurelia way using two-way data binding.
The second version will introduce Redux to handle the application state. We will use a vanilla approach, which means no additional plugin to handle the interop. That way you will learn how to use Aurelia's out of the box features to accommodate a Redux development process.
The final version will implement the undo/redo feature. Anyone who has built this kind of functionality from scratch knows that it is quite easy to get started, but things can quickly get out of hand. That's why we'll use the the redux-undo plugin to handle this for us.
Throughout the article you will see several references to the official Aurelia docs, to help you find additional information. All of the code listings also link back to their original source files.
So without any further ado, let's get started.
Scaffolding a New Aurelia App
Since we're focusing on the interaction with Aurelia, the example is based on Aurelia's new preferred way to scaffold an application, the Aurelia CLI.
Following the steps explained in CLI Docs, we install the CLI globally with the following command:
npm install aurelia-cli -g
Next, we'll create the new app using:
au new aurelia-redux
This will start a dialogue asking whether you would like to use the default setup or customize your choices. Select the default (ESNext) and opt to create the project and install the dependencies. Then change directory into your new project's folder (using
cd aurelia-redux) and start the development server with:au run --watch
If everything has gone according to plan, this will fire up a BrowserSync development server instance, listening by default on port 9000. Additionally, it will track changes made to your application and refresh when needed.
Adding Dependencies to the Bundler
The next step is to install the necessary dependencies for our upcoming project. Since the Aurelia CLI builds on top of npm modules we can do this with the following command:
npm install --save marked redux redux-undo
Ok, so let's go through each of those. Marked is a full-featured, easy to use markdown parser and compiler, which we're going to use for ... well for exactly what it says on the tin. Redux is the package for the library itself and redux-undo is a simple plugin to add undo/redo features for our application's state container.
Under the hood, the Aurelia CLI uses RequireJS and as such all dependencies are referenced via the Asynchronous Module Definition (AMD) format. Now what's left is to tell the Aurelia application how and where it can find those dependencies.
In order to do so open the
aurelia.json file found in your app's aurelia-project subfolder. If you scroll down to the bundles section you will see two objects. One for the app-bundle, containing your own app code, followed by the vendor-bundle used to bundle all of your app's dependencies in a separate bundle file. That object contains a property named dependencies and you guessed it, this is the place where we're going to add our additional ones.Manipulating the fileaurelia.jsonmanually, is currently a necessary step, but one which is going to be automated in future versions.
There are multiple ways to register custom dependencies, best understood by following the respective official Aurelia Docs. What we're going to add is the following code:
// file: aurelia_project/aurelia.json
...
{
"name": "text",
"path": "../scripts/text"
},
// START OF NEW DEPENDENCIES, DON'T COPY THIS LINE
{
"name": "marked",
"path": "../node_modules/marked",
"main": "marked.min"
},
{
"name": "redux",
"path": "../node_modules/redux/dist",
"main": "redux.min"
},
{
"name": "redux-undo",
"path": "../node_modules/redux-undo/lib",
"main": "index"
},
// END OF NEW DEPENDENCIES, DON'T COPY THIS LINE
{
"name": "aurelia-templating-resources",
"path": "../node_modules/aurelia-templating-resources/dist/amd",
"main": "aurelia-templating-resources"
},
...
Wiring the App Dependencies
Now that everything is set up you should go ahead and restart the CLI watcher to get your newly installed vendor dependencies properly bundled. Remember we do this with the following command:
au run --watch
That's it, now we're ready to get our hands dirty with some code.
Adding Some Styling
No markdown editor would be complete without some decent styling. We'll start off by including a stylish-looking font in
index.html in the root folder.<head>
<title>Aurelia MarkDown Editor</title>
<link href="https://fonts.googleapis.com/css?family=Passion+One:400,700|Roboto:300,400,500,700"
rel="stylesheet" type="text/css">
</head>
After that we'll add a bunch of styles to
Doing it the Aurelia Way
/src/styles.css. Rather than list all of the CSS here, I'd encourage you to have a look at the CSS file on GitHub and to use these styles in your own project.We will start off by creating a new custom element named
<markdown-aurelia> to act as our logical container. We do so by following Aurelia's default conventions of creating a ViewModel markdown-aurelia.js and a View markdown-aurelia.html, inside the src folder.Continue reading %Managing State in Aurelia: How to Use Aurelia with Redux%