Build an Image Gallery Using React, Redux and redux-saga

Building an Image Gallery

The image gallery we will build is a simple application that displays an array of image URLs loaded from a service (Flickr), and allows the user to select them individually.

It will be built with React, using Redux and redux-saga. React is being used as the core framework to take advantage of its virtual-dom implementation. Redux will handle the management of state within the application. Finally, we will use redux-saga to handle the complexity of asynchronous sequences.

We will write the gallery in ES6 (arrow functions, modules, and template strings!), so we will need to do a bit of project setup to get going.

Project Setup and Automation

There is a significant array of options when it comes to getting started with a React application. For this simple app, we want to keep it as minimal as possible. We are going to use Babel to transpile ES6 into good ol’ ES5 for the browser, budo/browserify to serve it locally, and tape to test.

Create a file called package.json in a new project folder and add the following contents to it:

With the package.json in place, you can run npm install in the project folder and install all of the dependencies that we will need.

We’re also going to need to configure Babel with a .babelrc file in the project folder that contains the Babel presets that we want to use:

.babelrc

123

{"presets":["es2015","react","stage-2"]}

This file tells babel that we will be using ES2015 (ES6), React, and stage-2 features of the emerging ECMAScript standard (ES2016).

The package.json has two standard scripts configured called start and test. For right now, we want to get start working so we can load the application. The start script is currently configured to look inside of a folder called src so create a folder called src in the project directory and add the following files:

The index.html loads the styles.css to give us some basic styling/layout. It also loads the script build.js, which is a generated file. Our main.js is a very basic React application that renders an h1 into the #root element inside of index.html. With these files in place, you should now be able to run npm start in the project folder and navigate to http://10.11.12.1:9966/ and see the following:

Now we will build the base Gallery React component.

Displaying some images in the gallery.

First thing’s first, and we want to get some images displayed as quickly as possible! We will create a Gallery component that will display our images. In the project folder, create a file called Gallery.js with the following contents.

We’ve hard coded an array of data into this component, which is a great way to start working quickly. The Gallery extends Component, and in its constructor we set the initial state of the component. Finally, we render a basic structure with some styled markup. The image-scroller element uses the images array to produce multiple elements using map.

For now, we are using the hard-coded image URLs (via the flickrImages array), and displaying the first image url as the selectedImage. We’re accessing these properties by setting a default initial state within the Gallery component class constructor.

We can add interactivity to the gallery with an event handler that calls the setState method on the Gallery component:

By adding handleThumbClick to the Gallery component class, we can access it in any elements onClick method. Note that we are using bind(this,image) in the onClick. By passing image as the second argument, it is sent as the first argument to handleThumbClick. This use of bind is an extermely handy way to pass context to an event handler.

Looking good! Now we have some interaction, and something that resembles an “app”. Now that we’ve dealt with getting the application running and displaying data, we can consider loading some remote data. The most obvious place to do that is one of the React component lifecycle methods. We will use componentDidMount and make a call to the Flickr API and load some images:

We’ve added a new method to the Gallery class. We are using React’s componentDidMount lifecycle method to trigger the loading of data from Flickr. Lifecycle methods are called by React at specific times in a component’s lifecycle. In this case, the method will be called whenever the component is added to the DOM. Note that the Gallery component is only added to the DOM once, so this will give us our initial load of images. For a more dynamic component that is loaded and unloaded over an application’s lifecycle, this might cause excessive service calls or other unforeseen results.

We are using the fetch browser API to make a request to Flickr. Fetch returns a promise that resolves with response object. Calling response.json() gives us another promise, which is the actual JSON result we are looking for. We’ll map over the photos to create an array of Flickr image urls.

Let’s be honest. This application is simple. We could stop right here and we’d have the basic requirements done. Maybe we add an error handler in the fetch promise chain, some logic to see if there are images and DONE! At this point you really have to stop and use your imagination a bit. Simple requirements rarely last in the real world. Soon the application will grow as feature requests roll in. Authentication, a slide show, the ability to load different galleries and images sets… This is not good enough.

So now that we have a working image gallery using React, we can start thinking about the foundation of patterns that we want to use to grow the application over time. The first order of business is to take away the Gallery component’s power to control the state of the application.

We are going to introduce Redux to manage state instead, so let’s get that setup.

Using Redux to manage state

Anytime you use setState in your application you’ve allowed the Component to become stateful. While this isn’t always bad, it can lead to some confusing application code over time, with state management spread from top to bottom in your application.

The Flux architecture is one solution that was introduced to help alleviate this. Flux moves logic and state into Stores. Stores are updated when Actions are dispatched in the application. Updates to Stores will trigger Views to be rendered with the new state.

Bootstrapping Redux

The first thing we need to do is get Redux bootstrapped and running in our application. We don’t have to install anything, that was all taken care of when we ran npm install, but we do need to import and configure Redux.

The reducer function is the brain of Redux. When an action is dispatched by the application, the reducer receives the action and creates the piece of application state that the reducer owns. Since reducers are pure functions, they can be composed together to create the complete state of the application. Let’s create a simple reducer in the src folder:

reducer.js

state – this is the data that represents the state of the application. The reducer function will use this state to construct the new state. If no state has changed as result of the action, the reducer will simply return the state input.

action – the event that has triggered the reducer. Actions are dispatched by the store, and handled by reducers. The action is required to have a type property that the reducer uses to apply changes to the new application state.

For right now, the images reducer will log to the console to prove that it is connected and ready for work. To use the reducer we need to configure redux in main.js:

We are going to import the createStore function from the Redux library. createStore is used to create the Redux store. For the most part, we don’t interact directly with the store, it is something that Redux manages for us behind the scenes.

We also need to import the reducer function that we’ve just created so that it can be delivered to the store.

We will use createStore(reducer) to configure the store with our application’s reducer. This example only has a single reducer, but createStore can take multiple reducers arguments. More on that a bit later!

Finally we import the higher-order Provider component from react-Redux. This will wrap our Gallery so that we can make easy use of Redux. We need to pass the store we just created to the Provider so that it can use it for us. You could use Redux without Provider, and in fact, React isn’t required to use Redux at all! That’s wonderful, but we are going to use Provider because it is very convenient.

If you open your developer tools console, you should see a message!

It may be a bit mysterious, but shows off an interesting point of Redux. All reducers receive all actions that are dispatched in the application. In this case we are seeing an action that Redux itself dispatches.

Connecting the gallery component

With Redux, we will use the concept of “connected” and “un-connected” components. A connected component is wired into the store, and coordinates and controls action events and the store. Usually a connected component will have children that are “pure components” that take data as input, and render when that data is updated. These children are unconnected components.

note: While React and Redux play very well together, React is not required for Redux. You can use Redux without React!

react-redux provides a convenient wrapper for React components that does most of the heavy lifting required to connect a React component to a Redux store. We will add that to Gallery and make it our primary connected component:

Importing the connect function from react-redux lets us export Gallery by wrapping it in the connect component. Notice that connect()(Gallery) puts Gallery in a second set of parentheses. This is because connect() returns a function that expects a React component as an argument. The call to connect() configures that function. Soon we’ll pass in arguments to connect to configure it for our applications specific actions and state structure.

We are also exporting the connect call as the default for this module. This is important! Now, when we import Gallery it will import the connected component and not the basic class.

If you look at the console log that we’ve added to the constructor, you will see that the Gallery component’s properties now include a dispatch function. This is part of what connect has modified for us, and gives us the ability to dispatch our own action objects to the applications reducers.

We can test it out by calling dispatch in the constructor. You should see a log statement from our reducer in your developer console. We’ve dispatched our first action! Actions are plain old javascript objects that have a required type property. They can have any number of other properties as well to pass along to the reducer, but the type property allows reducers to listen for specific actions that they are interested in.

Generally reducers use a switch block to filter messages they are interested in. The switch uses the action’s type, and the reducer does its work when it gets an action that matches one of the cases of the switch.

Our application is now wired to receive actions. Now we need to connect it to the state provided by the Redux store.

Default application state

Because we are using connect, we don’t need to interact with the Redux store directly. We are going to configure a default application state to provide the Redux store.

We’ve created a defaultState object that has an empty array as its images property. We will set the state to default in the images function parameters. Now, if we log out the state property in our test case, you’ll see that it isn’t undefined! The reducer needs to return the current state of the application. This is important! Right now, we aren’t making any changes, so we can just return the state. Note that we added a default case. The reducer should always return an object representing the state.

In the Gallery we can also connect the applications state by mapping it to properties:

We are going to remove all of the image loading and interaction in the connected component for now. If you look towards the bottom of Gallery you will notice that we created a function called mapStateToProps that takes a state argument and returns an object that puts state.images into a property called images. mapStateToProps is then passed as an argument to connect.

As the name suggests mapStateToProps is a function that takes the current state, and assigns it to properties of the component. If you console.log(props) in the constructor, you will see that we now have access to the images array that we set as the default state in our reducer!

If you update the images array in the defaultState you should see some images reappear in the gallery! Now we need to get image selection wired back up with an action that is dispatched when the user clicks a thumbnail.

Updating the state

So how do we update the state with a new selected image?

We’re going to configure the reducer to listen for an IMAGE_SELECTED action, and update the state with the action’s payload.

Now the reducer is ready to receive the IMAGE_SELECTED action should it be dispatched! Inside of the case, we are returning a new state object by “spreading” the existing state and overwriting the selectedImage property. Checkout more on the ...state object spread technique in this video. It’s excellent.

In the Gallery, we will use the dispatch function in the component props by calling it inside of the body of the onClick handler function. For now we are just writing it inline for convenience, but once we make that change, we can now click a thumbnail, and it will update the selected image via the reducer!

Using dispatch can be convenient way to quickly create generic actions, but soon we will want to make reusable actions that are well named. To do this, we will make use of “action creators”.

Action Creators

Action creators are functions that return configured action objects. We will add our first action creator to an new file called actions.js.

actions.js

This could now be imported directly into any file that needed to create a selectImage action! selectImage is a pure function that only returns data. It takes an image as an argument, and adds that to the action object it creates and returns.

note: We are returning a plain JavaScript object, but the second property image might be weird if you haven’t encountered this style before. Basically, in ES6, if you pass a property to an object like this it expands to image: 'whatever value was held by image' in the resulting object. Super handy.

We’ve added a mapActionCreatorsToProps function that takes the dispatch function as an argument. It returns the result of a call to bindActionCreators with our GalleryActions provided as an argument. Now if you log the props, you’ll see that Galleryno longer gets passed the dispatch function, and instead has a function called selectImage that we can use directly!

To review, we’ve done several things:

created a reducer that contains the initial (default) state of our application and listens for actions

created a store that consumes the reducer and provides a dispatcher that we can use to dispatch actions

connected our Gallery component to the store

mapped the store’s state to props that are passed to the Gallery

mapped an action creator function so that the Gallery can simply call selectImage(image) and the application state will update.

How do we use these patterns and load data from the remote data source?

This is where it gets interesting!

Asyncronous activity?

You may hear the term “side effects” used when discussing a functional style of programming. Side effects are things that occur outside the boundaries of the application. Within our cozy bubble, side effects aren’t really a problem, but when we reach out to a remote service the bubble is pierced. We lose some control, and we have to accept that fact.

In Redux, reducers don’t have side effects. This means that reducers don’t handle async activity in our application. We can’t use them to load our remote data because reducers are pure functions with no side effects.

Redux is wonderful, and if you don’t have and side-effects like asynchronous activity you could stop right here. If you’re creating more than the most trivial example, it is likely that you are loading data from a service, and this is of course async.

note: one of the coolest aspects of Redux is how tiny it is. It does so very little! It is intended to solve a very limited problem scope. Most applications will need to solve lots of problems! Luckily Redux provides the concept of “middleware”, which are basically bits of code that sit in the midel of the action –> reducer –> store triangle and provide a mechanism for introducing side effects like async calls to remote servers

One approach is to use thunks with the redux-thunk middleware. Thunks work great, but can get confusing for sequences of actions and can be challenging to test effectively.

select an initial image for display when the results have been received

handle any errors that might occur

This is all before the user has clicked anything in the application!

So how do we do it?

This is where redux-saga can be of great service to our application!

redux-saga

redux-saga is built to handle asynchronous actions in our Redux applications. It provides middleware and a handful of effects methods that make building complex sequences of asynchronous actions a breeze.

A saga is a generator function. Generators are an ES2015 addition to JavaScript. This might be your first encounter with generator functions, and if that’s the case, they might be a little weird. If that is the case, take a few minutes to read ES6 Generators in Depth and watch this short generators video. Don’t fret to much if you’re still scratching your head. To use redux-saga you won’t need a PhD in JavaScript Async Programming. Promise.

Because of the way generators work, we are able to create flat sequences of commands describing complex workflows within our application. The entire image loading sequence described above could look like this:

No matter how long you stare at the console, your “hello” will never arrive

This is because sayHello is a generator! Generators don’t execute immediately. If you changed the line to sayHello().next(); your greating will appear. Don’t worry, we won’t call next all the time. Like Redux, redux-saga is built to remove pain and bolierplate and make our development experience more pleasurable.

We’ve imported the applyMiddleware function from Redux, and the createSagaMiddleware from redux-saga. When we create the store, we need to supply Redux with the middleware that we want to use. In this case we call applyMiddleware and send it the result of createSagaMiddleware(sayHello). Behind the scenes redux-saga loads in the sayHello function, and politely calls the initial next for us.

It should greet you in the console!

Now let’s build a saga for loading images.

Loading Images with a Saga

We’ill get rid of the sayHello saga and replace it with a loadImages saga in sagas.js.

The fetchImages method returns a promise. We are going to call fetchImages, but we are going to use the yield keyword. By dark arts and sorcery, generators understand promises, and as the console log will show, we’ve yielded an array of image urls. Looking at loadImages, it looks like typical syncronous code. The yield keyword is the secret sauce that lets us code in this syncronous style for asyncronous activity.

Encapsulating our async API requests

Let’s define the api we want to use in its own file. It is nothing special. In fact, it’s the same code we used earlier to load Flickr images. We’re going to create a file called flickr.js in the src folder:

This isn’t strictly required, but it makes a lot of sense to me. We are at the very boundaries of our application, where things are a bit messy. By encapsulating the mechanics of the interaction with the remote API, our code will be cleaner and easier to update. It also makes it dead simple to completely swap out the image service provider! Nice.

We still need to get data out of our saga and into the application state. To handle this, we will utilize “effects” provided by redux-saga.

Update the application from a saga

We could probably call our saga with the dispatch function or store as an argument, but that approach would be unpleasant and perhaps a tad confusing over time. Instead, we’ll rely on a method provided by redux-saga called put.

First we will update reducer.js to handle a new action type IMAGES_LOADED

After importing put, we add another line to loadImages. It yields the result of the call the put which sends along an action object. Behind the scenes redux-saga dispatches that for us, and the reducer receives the message!

What if we don’t want to loadImages implicitly like this, simply because we have wired up a saga? How do we trigger a saga with a specific type of action?

Triggering saga workflows with actions

Sagas become much more useful if we have the ability to trigger their workflows with Redux actions. When we do this, we can leverage the power of sagas from any component in our app. First we will create a new saga called watchForLoadImages.

This new saga uses a while loop so that it is always active and ready. Inside of the loop we are yielding a call to a new method from redux-saga called take. Take listens for actions of a given type, and when they occur, it advances the saga to the next yield. In this case, we are yielding a call to loadImages, which initiates the loading of images.

Blocking and non-blocking effects

This works fine for our application, but there is a broader issue that we should be concerned with. The watchForLoadImages sage contains blocking effects. What does that mean? Well, it means that we can only execute a single LOAD_IMAGES workflow at a time! It isn’t obvious with a simple example like this, because we actually only load images once, but it is definitely a consideration. In fact, the general practice when listening for action evens is to use the fork effect instead of yield loadImages().

Using the fork helper will convert our watchForLoadImages into a non-blocking saga that can be executed regardless of whether or not a previous call is in progress. redux-saga provides two helpers, takeEvery and takeLatest that assist in these situations.

Selecting the default image

Sagas are sequences of actions, so we can add more aspects to a saga easily.

As part of the loadImages workflow, we can yield another call to put with the IMAGE_SELECTED action type and send along the image we want to select when images are loaded.

Handling errors

If something goes wrong inside of the saga, we might want to notify the application so that it can respond accordingly. Do do this, we simply wrap the workflow in a try/catch block, and yield a put with a nitification that has the error as the payload.

Testing Sagas

Using Redux makes testing most of our app a breeze. Check out this egghead course for lots of techniques for testing React in general.

One of the awesome aspects of redux-saga is how easy it makes testing these bits of asynchronous code. Testing async javascript can be a real chore. With sagas, we don’t need to jump through hoops to test this core functionality of our application. Sagas take the pain out of aync tests! Which means we will write more tests. Right?

We’ll go ahead and import everything we need for now, and add a single test. The test function takes a name and a function as arguments. Inside of the function, we create an instance of the sage generator. Armed with that instance, we can start advancing the saga to test each step.

The assert.deepEqual method takes two values and checks to see if they are equal (deeply!). The first is a call generator.next().value which advances the generator and gets the value. The next value is simple false. We want to see it fail! The final argument is a description of the expected behavior.

The test fails as expected and the results are interesting. The actual result is { TAKE: 'LOAD_IMAGES' }, which is the output we receive when we call take('LOAD_IMAGES');. In fact, our saga could yield an object instead of calling take, but take gives us a little sugar and eliminates annoying keystrokes.

Hmm, { _invoke: [Function: invoke] } is definitely not as obvious as the simple object that we got when yeilding take.

This is a problem. Luckily it’s one that redux-saga has solved in a nice way with effects like fork. take, fork, and other effect methods return and easily testable simple object. The object is a set of instructions for redux-saga to execute. This is beautiful for testing because we don’t have to worry about the actual side effects (like remote service calls). All we care about are the commands we are requesting to be executed.

Instead of a function invocation, we get a plain object. That object has the loadImages function embedded in it. The application loads exactly the same in the browser, but now we can easily test this step in the saga workflow.

Testing the loadImages saga is similar. We need to update yield fetchImages to yield fork(fetchImages).

123456789101112131415161718192021222324252627282930313233

test('loadImages',assert=>{constgen=loadImages();assert.deepEqual(gen.next().value,call(fetchImages),'loadImages should call the fetchImages api');constimages=[0];assert.deepEqual(gen.next(images).value,put({type:'IMAGES_LOADED',images}),'loadImages should dispatch an IMAGES_LOADED action with the images');assert.deepEqual(gen.next(images).value,put({type:'IMAGE_SELECTED',image:images[0]}),'loadImages should dispatch an IMAGE_SELECTED action with the first image');consterror='error';assert.deepEqual(gen.throw(error).value,put({type:'IMAGE_LOAD_FAILURE',error}),'loadImages should dispatch an IMAGE_LOAD_FAILURE if an error is thrown');assert.end();});

Take note of the last assert. It’s testing the catch by using throw instead of next on the generator. Another cool feature is the ability to send values in. Notice that we’ve created an images constant, and we pass that into next. The saga uses the value we pass in for the next step in the sequence.

It’s awesome, and this level of control is a dream when it comes to testing async activity!