What’s MERN?

Any web application is built using multiple technologies. The combinations of these technologies is called a “stack ,” popularized by the LAMP stack, which is an acronym for Linux, Apache, MySQL, PHP, which are all open-source software. As web development matured and their interactivity came to the fore, Single Page Applications (SPAs) became more popular. An SPA is a web application paradigm that avoids fetching the contents of an entire web page from the server to display new contents. It instead uses lightweight calls to the server to get some data or snippets and changes the web page. The result looks quite nifty as compared to the old way of reloading the page entirely. This brought about a rise in front-end frameworks, since a lot of the work was done on the front-end. At approximately the same time, though completely unrelated, NoSQL databases also started gaining popularity.

The MEAN (MongoDB, Express, AngularJS, Node.js) stack was one of the early open-source stacks that epitomized this shift toward SPAs and adoption of NoSQL. AngularJS, a front-end framework based on the Model View Controller (MVC) design pattern, anchored this stack. MongoDB, a very popular NoSQL database, was used for persistent data storage. Node.js, a server-side JavaScript runtime environment, and Express, a web-server built on Node.js, formed the middle-tier, or the web server. This stack was arguably the most popular stack for any new web application until a few years back.

Not exactly competing, but React, an alternate front-end technology created by Facebook, has been gaining popularity and offers an alternative to AngularJS. It thus replaces the “A” with an “R” in MEAN, to give us the MERN Stack. I said “not exactly” since React is not a full-fledged MVC framework. It is a JavaScript library for building user interfaces, so in some sense, it’s the View part of the MVC.

Although we pick a few defining technologies to define a stack, these are not enough to build a complete web application. Other tools are required to help the process of development, and many libraries are needed to complement React. This book is about building a complete web application based on the MERN stack and all these related tools and libraries.

Who Should Read This Book

Developers and architects who have prior experience in any web app stack other than the MERN stack will find the book useful for learning about this modern stack. Prior knowledge of how web applications work is required. Knowledge of JavaScript is also required. It is further assumed that the reader knows the basics of HTML and CSS. It will greatly help if you are also familiar with the version control tool git; you could try out the code just by cloning the git repository that holds all the source code described in this book and running each step by checking out a branch.

The code in the book uses the latest features of JavaScript (ES2015+), and it is assumed that you well-versed in these features such as classes, fat-arrow functions, const keyword, etc. Whenever I first use any of these modern JavaScript features, I will point it out using a note so that you are aware that it is a new feature. In case you are not familiar with a particular feature, you can read up on it as and when you encounter it.

If you have decided that your new app will use the MERN stack, then this book is a perfect enabler for you that lets you quickly get off the ground. Even if you have not, reading the book will get you excited about MERN and equip you with enough knowledge to make a choice for a future project. The most important thing you will learn is to put together multiple technologies and build a complete, functional web application, and you can be called a full-stack developer or architect on MERN.

Structure of the Book

Although the focus of the book is to let you learn how to build a complete web application, most of the book revolves around React. That’s just because, as is true of most modern SPAs, the front-end code forms the bulk. And in this case, React is used for the front-end.

The tone of the book is tutorial-like and designed for learning by doing. We will build a web application during the course of the book. I use the term “we” because you will need to write code just as I show you the code that is to be written as part of the plentiful code listings. Unless you write the code yourself alongside me and solve the exercises, you will not get the full benefit of the book. I encourage you not to copy-paste; instead please type out the code. I find this very valuable in the learning process. There are very small nuances—e.g., types of quotes—that can cause a big difference. When you type out the code, you are much more conscious of this than when you are just reading it.

Sometimes, you may run into situations where what you typed in doesn’t work. In such cases, you may want to copy-paste to ensure that the code is correct and overcomes any typos you may have made. In such cases, do not copy-paste from the electronic version of the book, as the typesetting may not be faithful to the actual code. I have created a GitHub repository at https://github.com/vasansr/pro-mern-stack-2 for you to compare, and in unavoidable circumstances, to copy-paste from.

I have also added a checkpoint (a git branch in fact) after every change that can be tested in isolation so that you can look at the exact diffs between two checkpoints, online. The checkpoints and links to the diffs are listed in the home page (the README) of the repository. You may find this more useful than looking at the entire source, or even the listings in the text of this book, as GitHub diffs are far more expressive than what I can show in print.

Rather than cover one topic or technology per section, I have adopted a more practical and problem-solving approach. We will have developed a full-fledged working application by the end of the book, but we’ll start small with a Hello World example. Just as in a real project, we will add more features to the application as we progress. When we do this, we’ll encounter tasks that need additional concepts or knowledge to proceed. For each of these, I will introduce the concept or technology that can be used, and I’ll discuss that in detail.

Thus, you may not find every chapter or section devoted purely to one topic or technology. Some chapters may focus on a technology and others may address a set of goals we want to achieve in the application. We will be switching between technologies and tools as we progress.

I have included exercises wherever possible, which makes you either think or look up various resources on the Internet. This is so that you know where to get additional information for things that are not covered in the book, typically very advanced topics or APIs.

I have chosen an issue-tracking application as the application that we’ll build together. It’s something most developers can relate to, at the same time has many of the attributes and requirements that any enterprise application will have, commonly referred to as a “CRUD” application (CRUD stands for Create, Read, Update, Delete of a database record).

Conventions

Many of the conventions used in the book quite obvious, so I’ll not explain all of them. I’ll only cover some conventions with respect to how the sections are structured and how changes to the code are shown because it’s not very obvious.

Each chapter has multiple sections, and each section is devoted to one set of code changes that results in a working application that can be run and tested. A section can have multiple listings, but each of them may not be testable by itself. Every section will also have a corresponding entry in the GitHub repository, where you can see the complete source of the application as of the end of that section, as well as the differences between the previous and the current section. You will find the difference view very useful to identify the changes made in the section.

All code changes will appear in listings within the section, but please do not rely on their accuracy. The reliable and working code can be found in the GitHub repository, which could even have undergone last-minute changes that couldn’t make it to the printed book in time. All listings will have a listing caption, which will include the name of the file being changed or created.

You may use the GitHub repository to report problems in the printed book. But before you do that, do check the existing list of issues to see if anyone else has reported the same. I will monitor the issues and post resolutions and, if necessary, correct the code in the GitHub repository.

A listing is a full listing if it contains a file, a class, a function, or an object in its entirety. A full listing may also contain two or more classes, functions, or objects, but not multiple files. In such a case, if the entities are not consecutive, I’ll use ellipses to indicate chunks of unchanged code.

All commands used in the book can also be found in the GitHub repository in a file called commands.md. This is so that errors in the book can be corrected after the book has been published, and also to be a more reliable source for copy-pasting. Again, you are encouraged not to copy-paste these commands, but if you are forced to because you find something is not working, then please copy-paste from the GitHub repository rather than the book’s text.

These commands are also collected in one file, called mongoCommands.md in the GitHub repository.

What You Need

You will need a computer that can run your server and do other tasks such as compilation. You will also need a browser to test your application. I recommend a Linux-based computer such as Ubuntu, or a Mac as your development server, but with minor changes, you could also use a Windows PC.

Running Node.js directly on Windows will also work, but the code samples in this book assume a Linux-based PC or Mac. If you choose to run directly on a Windows PC, you may have to make appropriate changes, especially when running commands in the shell, using a copy instead of using soft links, and in rare cases, to deal with \ vs. / in path separators.

One option would be to try to run an Ubuntu server Virtual Machine (VM) using Vagrant ( https://www.vagrantup.com/ ). This is helpful because you will eventually deploy your code on a Linux-based server, and it is best to get used to that environment from the beginning. But you may find it difficult to edit files, because in an Ubuntu server, you only have a console. An Ubuntu desktop VM may work better for you, but it will need more memory.

Further, to keep the book concise, I have not included installation instructions for packages, and they are different for different operating systems. You will need to follow the installation instructions from the package providers’ websites. And in many cases, I have not included direct links to websites and I ask you to look them up. This is due to a couple of reasons. The first is to let you learn by yourself how to search for these. The second is that any link I provide may have moved to another location due to the fast-paced changes that the MERN stack was experiencing at the time of writing this book.

MERN Components

I’ll give a quick introduction to the main components that form the MERN stack, and a few other libraries and tools that we’ll be using to build our web application. I’ll just touch upon the salient features and leave the details to other chapters where they are more appropriate.

Node.js

Simply put, Node.js is JavaScript outside of a browser. The creators of Node.js just took Chrome’s V8 JavaScript engine and made it run independently as a JavaScript runtime. If you are familiar with the Java runtime that runs Java programs, you can easily relate to the JavaScript runtime: the Node.js runtime runs JavaScript programs.

Although you may find people who don’t think Node.js is fit for production use, claiming it was meant for the browser, there are many industry leaders who have chosen Node.js. Netflix, Uber, and LinkedIn are a few companies that use Node.js in production, and that should lend credibility as a robust and scalable environment to run the back-end of any application.

Node.js Modules

In a browser, you can load multiple JavaScript files, but you need an HTML page to do all that. You cannot refer another JavaScript file from one JavaScript file. But for Node.js, there is no HTML page that starts it all. In the absence of the enclosing HTML page, Node.js uses its own module system based on CommonJS to put together multiple JavaScript files.

Modules are like libraries. You can include the functionality of another JavaScript file (provided it’s written to follow a module’s specifications) by using the require keyword (which you won’t find in a browser’s JavaScript). You can therefore split your code into files or modules for the sake of better organization and load them using require. I’ll talk about the exact syntax in a later chapter; at this point it’s enough to note that compared to JavaScript on the browser, there is a cleaner way to modularize your code using Node.js.

Node.js ships with a bunch of core modules compiled into the binary. These modules provide access to the operating system elements such as the file system, networking, input/output, etc. They also provide some utility functions that are commonly required by most programs.

Apart from your own files and the core modules, you can also find a great amount of third-party open-source libraries available for easy installation. That brings us to npm.

Node.js and npm

npm is the default package manager for Node.js. You can use npm to install third-party libraries (packages) and manage dependencies between them. The npm registry ( www.npmjs.com ) is a public repository of all modules published by people for the purpose of sharing.

Although npm started off as a repository for Node.js modules, it quickly transformed into a package manager for delivering other JavaScript based modules, notably, those that can be used in the browser. jQuery, by far the most popular client-side JavaScript library, is available as an npm module. In fact, even though React is largely client-side code and can be included directly in your HTML as a script file, it is recommended instead that React is installed via npm. But once it’s installed as a package, we need something to put all the code together that can be included in the HTML so that the browser can get access to the code. For this, there are build tools such as Browserify or Webpack that can put together your own modules as well as third-party libraries in a bundle that can be included in the HTML.

As of writing this book, npm tops the list of modules or package repositories, having more than 450,000 packages (see Figure 1-1). Maven, which used to be the biggest two years back, has fewer than half the number now. This shows that npm is not just the largest, but also the fastest growing repository. It is often said that the success of Node.js is largely owed to npm and the module ecosystem that has sprung around it.

npm is not just easy to use both for creating and using modules; it also has a unique conflict resolution technique that allows multiple conflicting versions of a module to exist side-by-side to satisfy dependencies. Thus, in most cases, npm just works.

Node.js is Event Driven

Node.js has an asynchronous, event driven, non-blocking input/output (I/O) model, as opposed to using threads to achieve multi-tasking.

Most other languages depend on threads to do things simultaneously. But in fact, there is no such thing as simultaneous when it comes to a single processor running your code. Threads give the feeling of simultaneousness by letting other pieces of code run while one piece waits (blocks) for some event to complete. Typically, these are I/O events such as reading from a file or communicating over the network. For example, on one line, you make a call to open a file, and on the next line, you have your file handle ready. What really happens is that your code is blocked (doing nothing) while the file is being opened. If you have another thread running, the operating system or the language will switch out this code and start running some other code during the blocked period.

Node.js, on the other hand, has no threads. It relies on callbacks to let you know that a pending task is completed. So, if you write a line of code to open a file, you supply it with a callback function to receive the results—the file handle. On the next line, you continue to do other things that don’t require the file handle. If you are used to asynchronous Ajax calls, you will immediately know what I mean. Event driven programming is natural to Node.js due to the underlying language constructs of JavaScript such as closures.

Node.js achieves multi-tasking using an event loop. This is nothing but a queue of events that need to be processed, and callbacks to be run on those events. In the previous example, the file being ready to be read will be an event that will trigger the callback you supplied while opening it. If you don’t understand this completely, don’t worry. The examples in the rest of this book should make you comfortable about how it really works.

On the one hand, an event-based approach makes Node.js applications fast and lets the programmer be blissfully oblivious of semaphores and locks that are utilized to synchronize multi-threaded events. On the other hand, writing code that is inherently asynchronous takes some learning and practice.

Why MERN?

So now you have a fair idea of the MERN stack and what it comprises. But is it really far superior to any other stack, say, LAMP, MEAN, etc.? By all means, any of these stacks are good enough for most modern web applications. All said and done, familiarity is the crux of productivity in software, so I wouldn’t advise a MERN beginner to blindly start their new project on MERN, especially if they have an aggressive deadline. I’d advise them to choose the stack that they are already familiar with.

But MERN does have its special place. It is ideally suited for web applications that have a large amount of interactivity built into the front-end. Go back and re-read the section on “Why Facebook Built React,” as it will give you some insights. You could perhaps achieve the same with other stacks, but you’ll find that it is most convenient to do so with MERN. So, if you do have a choice of stacks, and the luxury of a little time to get familiar, you may find that MERN is a good choice. I’ll talk about a few things that I like about MERN, and these may help you decide.

Isomorphic

SPAs used to have the problem hat they were not SEO friendly, because a search engine would not make Ajax calls to fetch data or run JavaScript code to render the page. One had to use workarounds like running PhantomJS on the server to pseudo-generate HTML pages, or use Prerender.io services that did the same for us. This introduced additional complexity.

With the MERN stack, serving complete pages out of the server is natural and doesn’t require tools that are after-thoughts. This is possible because React runs on JavaScript, which is the same on the client or the server. When React-based code runs on the browser, it gets data from the server and constructs the page (DOM) in the browser. This is the SPA way of rendering the UI. If we wanted to generate the same page in the server for search engine bots, the same React-based code can be used to get the data from an API server and construct the page (this time, as an HTML) and stream that back to the client. This is called server-side rendering (SSR).

Figure 1-2 compares these two modes of operation. What makes this possible is the fact that the same language is used to run the UI construction code in the server and the browser: JavaScript. This is what is meant by the term isomorphic: the same code can be run on the browser or the server. We’ll discuss SSR in depth and how it works in Chapter 12. At this point, it is sufficient to appreciate that the same code can be run on the browser and the client to achieve the two different modes of operation.

In fact, React Native has taken it to another extreme: it can even produce a mobile application’s UI. I don’t cover React Native in this book, but this fact should give you a feel of how React is structured and what it can do for you in the future.

Summary

This book lets you experience what it takes, and what it is like, to develop an application using the MERN stack.

In this chapter, we discussed the reasons that make MERN a compelling choice for any web application, which included the advantages of a single programming language throughout the stack, characteristics of a NoSQL database, and the isomorphism of React. I hope these reasons convince you to try out the MERN stack if not adopt it.

Finally, I hope you are really excited to learn about the MERN stack. So, without much ado, we’ll jump into code right in the next chapter and create the most basic of applications: the Hello World application.

Server-Less Hello World

To quickly get off the ground , let’s write a simple piece of code in a single HTML file that uses React to display a simple page on the browser. No installations, downloads, or server! All you need is a modern browser that can run the code that we write.

Let’s start creating this HTML file and call it index.html. You can use your favorite editor and save this file anywhere on your file system. Let’s start with the basic HTML tags such as <html>, <head>, and <body>. Then, let’s include the React library.

The type can be any HTML tag such as the string 'div', or a React component (which we will start creating in the next chapter). props is an object containing HTML attributes or custom component properties. The last parameter(s) is zero or more children elements, which again are created using the createElement() function itself.

A React element (the result of a React.createElement() call) is a JavaScript object that represents what is shown on screen. Since it can be a nested collection of other elements and can depict everything on the entire screen, it is also called the virtual DOM . Note that this is not yet the real DOM, which is in the browser’s memory and that is why it is called a virtual DOM. It resides in the JavaScript engine’s memory as a deeply nested set of React elements, which are also JavaScript objects. A React element contains not just the details of what DOM elements need to be created, but also some additional information about the tree that helps in optimization.

Each of these React elements needs to be transferred to the real DOM for the user interface to be constructed on screen. To do this, a series of document.createElement() calls needs to be made corresponding to each of the React elements. The ReactDOM does this when the ReactDOM.render() function is called. This function takes in as arguments the element that needs to be rendered and the DOM element that it needs to be placed under.

You can test this file by opening it in a browser. It may take a few seconds to load the React libraries, but soon enough, you should see the browser displaying the caption, as seen in Figure 2-1. You should also be able to hover over the text or anywhere to its right side within the boundaries of the outer div, and you should be able to see the tooltip “Outer div” pop up.

JSX

The simple element that we created in the previous section was easy to write using React.createElement() calls . But imagine writing a deeply nested hierarchy of elements and components: it can get pretty complex. Also, the actual DOM can’t be easily visualized when using the function calls as it can be visualized if it were plain HTML.

Note that although it is strikingly close to HTML syntax, it is not HTML. Note also that the markup is not enclosed within quotes, so it is not a string that can be used as an innerHTML either. It is JSX, and it can be freely mixed with JavaScript.

Now, given all the differences and the complexity in comparison to HTML, why do you need to learn JSX? What value does it add? Why not write the JavaScript itself directly? One of the things I talked about in the Introduction chapter is that MERN has just one language throughout; isn’t this contrary to that?

As we explore React further, you will soon find that the differences between HTML and JSX are not earth-shaking and they are very logical. You will not need to remember a lot or need to look up things as long as you understand and internalize the logic. Though writing JavaScript directly to create the virtual DOM elements is indeed an option, I find that it is quite tedious and doesn’t help me visualize the DOM.

Further, since you probably already know the basic HTML syntax, writing JSX will probably work best. It is easy to understand how the screen will look when you read JSX, because it is very similar to HTML . So, for the rest of the book, we use JSX.

When you test this set of changes, you will find no difference in the appearance of the page, but it could be a wee bit slower due to the compilation done by Babel. But don’t worry. We’ll soon switch to compiling JSX at build-time rather than at runtime to get rid of the performance impact. Note that the code will not work on older browsers yet; you may get errors in the script babel.min.js.

The file index.html can be found under a directory called public in the GitHub repository; this is where the file will eventually end up.

Project Setup

The server-less setup allowed you to get familiarized with React without any installations or firing up a server. But as you may have noticed, it's good neither for development nor for production. During development, some additional time is introduced for loading the scripts from a Content Delivery Network or CDN. If you take a look at the size of each of the scripts using the Network tab of the browser's developer console, you'll see that the babel compiler (even the minified version) is quite large. On production, especially in larger projects, runtime compilation of JSX to JavaScript will slow down the page loading and affect user experience.

So, let's get a little organized and serve all files from an HTTP server. We will, of course, use some other components of the MERN stack to achieve this. But before we do all that, let’s set up our project and folders in which we will be saving the files and installing libraries.

The commands that we will be typing in the shell have been collected together in a file called commands.md in the root of the GitHub repository.

Express

Express, if you remember in the introduction in the previous chapter, is the best way to run an HTTP server in the Node.js environment. For starters, we'll use Express to serve only static files. This is so that we get used to what Express does, without getting into a lot of server-side coding. We’ll serve the index.html file that we created in the previous section via Express.

require is a JavaScript keyword specific to Node.js, and this is used to import other modules. This keyword is not part of browser-side JavaScript because there was no concept of including other JavaScript files. All needed scripts were included directly in HTML files only. ES2015 specification came up with a way to include other files using the import keyword, but before the specification came out, Node.js had to invent its own using require. It’s also known as the CommonJS way of including other modules.

In the previous line, we loaded up the module called express and saved the top-level thing that the module exports, in the constant named express. Node.js allows the thing to be a function, an object, or whatever can fit into a variable. The type and form of what the module exports is really up to the module, and the documentation of the module will tell you how to use it.

In the case of Express, the module exports a function that can be used to instantiate an application. We just assigned this function to the variable express .

Now that we have a handle to the application, let’s set it up. Express is a framework that does minimal work by itself; instead, it gets most of the job done by functions called middleware. A middleware is a function that takes in an HTTP request and response object, plus the next middleware function in the chain. The function can look at and modify the request and response objects, respond to requests, or decide to continue with middleware chain by calling the next middleware function.

The argument to the static() function is the directory where the middleware should look for the files, relative to where the app is being run. For the application we’ll build as part of this book, we’ll store all static files in the public directory under the root of our project. Let’s create this new directory, public, under the project root and move index.html that we created in the previous section to this new directory.

The first argument is optional and defaults to '/' if not specified, so we could skip it too.

Finally, now that the application is set up, we’ll need to start the server and let it serve HTTP requests. The listen() method of the application starts the server and waits eternally for requests. It takes in a port number as the first argument. Let’s use the port 3000, an arbitrary port. We won’t use port 80, the usual HTTP port, because to listen to that port we need to have administrative (superuser) privileges.

Now, we are ready to start the web server and serve index.html. If you are looking at the GitHub repository for the code, you will find server.js under a directory called server. But at this point, the file needs to be in the root of the project directory.

You should see a message saying the application has started on port 3000. Now, open your browser and type http://localhost:3000/index.html in the URL bar. You should see the same Hello World page that we created in the previous section. If you see a 404 error message, maybe you have not moved index.html to the public directory .

The static middleware function served the contents of the index.html file from the public directory, as it matched the request URL. But it is also smart enough to translate a request to / (the root of the website) and respond by looking for an index.html in the directory. This is similar to what other static web servers such as Apache do. Thus, typing just http://localhost:3000/ is good enough to get the Hello World page.

When this is executed, npm looks for the file server.js and runs it using Node.js. So, let’s stop the server (using Ctrl+C on the command shell) and restart the server using npm start. You should see the same message saying the server has been started.

But what if we had a different starting point for the server? In fact, we want all the server-related files to go into a directory called server. So, let’s create that directory and move server.js into that directory.

Thus, if the server starting point is anything other than server.js in the root directory, the full command line has to be specified in the scripts section of package.json.

Note that there is also a field called main in package.json. When we initialized this file, the value of this field was set to index.js automatically. This field is not meant for indicating the starting point of the server. Instead, if the package was a module (as opposed to an application), index.js would have been the file to load when the project is imported as a module using require() in other projects. Since this project is not a module that can be imported in other projects, this field is not of any interest to us, and neither do we have index.js in the source code.

Now, we can use npm start and see the familiar application started message and test it out one final time. At this point in time, it’s good to check out the GitHub repository and look at the diffs for this section. In particular, take a look at changes in an existing file, package.json, to familiarize yourself with how changes within a file are shown in the book and how the same changes are seen in GitHub as diffs.

Separate Script File

In all the previous sections, the transformation of JSX to JavaScript happens at runtime. This is inefficient and quite unnecessary. Let’s instead move the transformation to the build stage in our development, so that we can deploy a ready-to-use distribution of the application.

At this point, the app should continue to work as before. If you point your browser to http://localhost:3000, you should see the same Hello World message. But we have only separated the files; we have not moved the transform to build time. The JSX continues to get transformed by the Babel library script, which was executed in the browser. We’ll move the transform to build time in the next section.

JSX Transform

Let’s now create a new directory to keep all the JSX files, which will be transformed into plain JavaScript and into the public folder. Let's call this directory src and move App.jsx into this directory.

If you look at the output directory public, you will see that there is a new file called App.js in there. If you open the file in your editor, you can see that the JSX elements have been converted to React.createElement() calls . Note that the Babel compilation automatically used the extension .js for the output file, which indicates that it is pure JavaScript.

If you test this set of changes, you should see that things work as before. For good measure, you could use the browser's developer console to ensure it is App.js that's being fetched, and not App.jsx. The developer console can be found on most browsers; you may need to look at your browser’s documentation for instructions to get to it.

Older Browsers Support

I’d mentioned earlier that the JavaScript code will work in all modern browsers that support ES2015. But what if we need to support older browsers, for example, Internet Explorer? The older browsers don’t support things like Arrow Functions and the Array.from() method . In fact, running the code at this point in IE 11 or earlier should throw a console error message saying Object.assign is not a function.

If you transform this using Babel, restart the server and point a browser at it. You will find that it works on most modern browsers. But, if you look at the transformed file, App.js, you will see that the JavaScript itself has not been changed, only the JSX has been replaced with React.createElement() calls . This is sure to fail on older browsers that neither recognize the arrow function syntax or the Array.from() method .

Now if you inspect the output of the transform, App.js, you will see that arrow functions have been replaced with regular functions.

That’s great, but how does one know which plugins have to be used? It’s going to be tedious to find out which browsers support what syntax and what transforms we’ve to choose for each. Fortunately, Babel does the job of automatically figuring this out via a preset called preset-env. This preset lets us specify the target browsers that we need to support and automatically applies all the transforms and plugins that are required to support those browsers.

Instead of using the command-line (which can get quite lengthy if we do use it), let’s specify the presets that need to be used in a configuration file. Babel looks for this in a file called .babelrc. In fact, there can be a .babelrc file in different directories, and the settings for files in that directory can be specified in each of those separately. Since we have all the client-side code in the directory called src, let’s create this file in that directory.

If you run this command and then inspect the generated App.js, you will find that the arrow function has been replaced with a regular function and also that the string interpolation has been replaced with a string concatenation. If you take out the line ie: "11" from the configuration file and re-run the transform, you’ll find that these transformations are no longer there in the output file, because the browsers that we’re targeting already support these features natively.

But even with these transformations, if you test on an Internet Explorer version 11, the code will still not work. That’s because it’s not just the transformations; there are some built-ins such as Array.find() that just aren’t there in the browser. Note that no amount of compilation or transformation can add a bunch of code like the Array.find() implementation. We really need these implementations to be available at runtime as a library of functions.

Now, the code can work on Internet Explorer as well. Figure 2-2 shows how the new Hello World screen should look.

Automate

Apart from being able to start the project using npm start, npm has the ability to define other custom commands. This is especially useful when there are many command line parameters for the command and typing them out on the shell becomes tedious. (Didn’t I say npm was powerful? This is one of the things that it does, even though this is not real package manager functionality.) These custom commands can be specified in the scripts section of package.json. These can then be run using npm run <script> from the console.

After this, if you run npm start again to start the server, you can see any changes to App.jsx reflected in the application.

It is essentially the same command as compile, but with two extra command line options, --watch and --verbose. The first option instructs Babel to watch for changes in source files, and the second one causes it to print out a line in the console whenever a change causes a recompilation. This is just to give a reassurance that a compile has in fact taken place whenever a change is made, provided you keep a watch on the console running this command.

If you now run the new command using npm run watch , you will notice that it does one transform, but it doesn’t return to the shell. It’s actually waiting in a permanent loop, watching for changes to the source files. So, to run the server, another terminal is needed, where npm start can be executed.

If you make make a small change to App.jsx and save the file, you’ll see that App.js in the public directory is regenerated. And, when you refresh the browser, you can see those changes without having to manually recompile. You can also make any changes to server.js and see that the server starts, with a message on the console that says the server is being restarted.

Summary

In this chapter, you learned the basics of how React applications can be built. We started with a simple piece of code written in React JSX that we compiled at runtime, then we moved the compilation as well as serving the file to the server.

We used nvm to install Node.js; you saw how npm can be used not just to install Node.js packages, but also to save command-line instructions in conventional or easy-to-spot scripts. We then used Babel, to transpile, that is, transform or compile from one specification of the language to another to support older browsers. Babel also helped us transform JSX into pure JavaScript.

You also got a whiff of what Node.js with Express can do. We did not use MongoDB, the M in the MERN stack, but I hope you got a good view of the other components of the stack.

By now, you should also have gotten familiar with how the book’s GitHub repository is organized and the conventions used in the book. For every section, there is a testable set of code that you can compare your own typed out code with. Importantly, the diffs between each step are valuable to understand the exact changes that were made in each step. Once again, note that the code in the GitHub repository is the one to rely on, with up-to-date changes that couldn’t make it to the printed book. If you find that you have followed the book verbatim, yet things don’t work as expected, do consult the GitHub repository to see if the printed book’s errors have been corrected there.

In the next two chapters, we’ll dive deeper into React, then surface up to look at the big picture, dealing with APIs, MongoDB, and Express in later chapters.

Answers to Exercises

Issue Tracker

I’m sure that most of you are familiar with GitHub Issues or Jira. These applications help you create a bunch of issues or bugs, assign them to people, and track their statuses. These are essentially CRUD applications (Create, Read, Update, and Delete a record in a database) that manage a list of objects or entities. The CRUD pattern is so useful because pretty much all enterprise applications are built around the CRUD pattern on different entities or objects.

In the case of the Issue Tracker, we’ll only deal with a single object or record, because that’s good enough to depict the pattern. Once you grasp the fundamentals of how to implement the CRUD pattern in MERN, you’ll be able to replicate the pattern and create a real-life application.

Note that I’ve included different types of fields (lists, date, number, text) to make sure you learn how to deal with different data types. We’ll start simple, build one feature at a time, and learn about the MERN stack as we go along.

In this chapter, we’ll create React classes and instantiate components. We’ll also create bigger components by putting together smaller components. Finally, we’ll pass data among these components and create components dynamically from data. In terms of features, the objective in this chapter is to lay out the main page of the Issue Tracker: a list of issues. We’ll hard-code the data that is used to display the page and leave retrieval of the data from the server to a later chapter.

React Classes

In this section, the objective is to convert the single-line JSX into a simple React component instantiated from a React class, so that we can later use the full power of the first class React components.

React classes are used to create real components (as opposed to templated HTML where we created a Hello World message based on a variable, which we created in the previous chapter). These classes can then be reused within other components, handle events, and so much more. To start with, let’s replace the Hello World example with a simple class forming the starting point for the Issue Tracker application.

React classes are created by extending React.Component, the base class from which all custom classes must be derived. Within the class definition, at the minimum, a render() method is needed. This method is what React calls when it needs to display the component in the UI.

There are other methods with special meaning to React that can be implemented, called the Lifecycle methods. These provide hooks into various stages of the component formation and other events. We’ll discuss other Lifecycle functions in later chapters. But render() is one that must be present, otherwise the component will have no screen presence. The render() function is supposed to return an element (which can be either a native HTML element such as a <div> or an instance of another React component).

In essence, the JSX element is now returned from the render() method of the component class called Hello World. The brackets around the JSX representation of the Hello World element are not necessary, but it is a convention that is normally used to make the code more readable, especially when the JSX spans multiple lines.

Now, this element can be used in place of the <div> element to render inside the node called contents, as before. It’s worth noting here that div and h1 are built-in internal React components or elements that could be directly instantiated. Whereas HelloWorld is something that we defined and later instantiated. And within HelloWorld, we used React’s built-in div component. The new, changed App.jsx is shown in Listing 3-1.

By now you should be running npm run watch in a console and have started the server using npm start in a separate console. Thus, any changes to App.jsx should have been automatically compiled. So, if you refresh your browser, you should see the greeting with all the continents, just as before.

Composing Components

In the previous section, you saw how to build a component by putting together built-in React components that are HTML element equivalents. It’s possible to build a component that uses other user-defined components as well, and that’s what we will explore in this section.

Component composition is one of the most powerful features of React. This way, the UI can be split into smaller independent pieces so that each piece can be coded and reasoned in isolation, making it easier to build and understand a complex UI. Using components rather than building the UI in a monolithic fashion also encourages reuse. We’ll see in a later chapter how one of the components that we built could easily be reused, even though we hadn’t thought of reuse at the time of building the component.

Let’s design the main page of the application to show a list of issues, with an ability to filter the issues and create a new issue. Thus, it will have three parts: a filter to select which issues to display, the list of issues, and finally an entry form for adding an issue. We’re focusing on composing the components at this point in time, so we’ll only use placeholders for these three parts. The structure and hierarchy of the user interface is shown in Figure 3-1.

Now let’s add a render() method . Within this method, let’s add an instance of each of the new placeholder classes separated by a <hr> or horizontal line. As you saw in the exercise of the earlier section, since the return of render() has to be a single element, these elements have to be enclosed within a <div> or a React Fragment component. The Fragment component is like an enclosing <div> but it has no effect on the DOM.

Ideally, each component should be written as an independent file. But at the moment, we only have placeholders, so for the sake of brevity, we’ll keep all the classes in the same file. Also, you haven’t learned how to put multiple class files together. At a later stage, when the classes are expanded to their actual content and we also have a way of building or referring to once class from another, we’ll separate them out.

The effect of this code will be an uninteresting page, as shown in Figure 3-2.

Passing Data Using Properties

Composing components without any variables is not so interesting. It should be possible to pass different input data from a parent component to a child component and make it render differently on different instances. In the Issue Tracker application, one such component that can be instantiated with different inputs is a table-row showing an individual issue. Depending on the inputs (an issue), the row can display different data. The new structure of the UI is shown in Figure 3-3.

In fact, the way to switch to the JavaScript world within any JSX snippet is to use curly braces. In the previous chapter, we used this to display the Hello World message, which was a JavaScript variable called message using the syntax {message}.

In this case, we passed across a simple string. Other data types and even JavaScript objects can be passed this way. Any JavaScript expression can be passed along, by using curly braces ({}) instead of quotes, because the curly braces switches into the JavaScript world.

So, let’s pass the issue’s title (as a string), its ID (as a number), and the row style (as an object) from IssueTable to IssueRow. Within the IssueRow class, we’ll use these passed-in properties to display the ID and title and set the style of the row, by accessing these properties through this.props.

We used the attribute style for the table-cell just as we would have used it in regular HTML. But note that this is not really an HTML attribute. Instead, it is a property being passed on to the built-in React component <td>. It’s just that the style property in the td component is interpreted and set as the HTML style attribute. In most cases, like style, the name of the attribute is the same as the HTML attribute, but for a few attributes causing conflict with JavaScript reserved words, naming requirements are different. Thus, the class HTML attribute needs to be className in JSX. Also, hyphens in the HTML attributes need to be replaced by camel cased names, for example, max-length becomes maxLength in JSX.

A complete list of DOM elements and how attributes for these need to be specified can be found in the React Documentation at https://reactjs.org/docs/dom-elements.html .

Now that we have an IssueRow component receiving the properties, let’s pass them from the parent, IssueTable. The ID and the title are straightforward, but the style we need to pass on has a special convention of specification in React and JSX.

Rather than a CSS kind of string, React needs it to be specified as an object with a specific convention containing a series of JavaScript key-value pairs. The keys are the same as the CSS style name, except that instead of dashes (like border-collapse), they are camel cased (like borderCollapse). The values are CSS style values, just as in CSS. There is also a special shorthand for specifying pixel values; you can just use a number (like 4) instead of a string "4px".

Note that we are not using string-like quotes for the Issue ID since it is a number or for rowStyle since it is an object. We instead use the curly braces, which makes it a JavaScript expression.

Now, let’s construct the IssueTable component, which is essentially a <table>, with a header row and two columns (ID and title), and two hard-coded IssueRow components. Let’s also specify an inline style for the table to indicate a collapsed border and use the same rowStyle variable to specify the header row styles, to make it look uniform.

Figure 3-4 shows the effect of these changes in the code.

Passing Data Using Children

There is another way to pass data to other components, using the contents of the HTML-like node of the component. In the child component, this can be accessed using a special field of this.props called this.props.children.

Just like in regular HTML, React components can be nested. In the Hello World example, we nested a <h1> element inside a <div>. When the components are converted to HTML elements, the elements nest in the same order. React components can act like the <div> and take in nested elements. In such cases, the JSX expression will need to include both the opening and closing tags, with child elements nested in them.

The result of these changes on the output will be minimal, just a little formatting in the title of the second issue will be visible. This is shown in Figure 3-5.

Dynamic Composition

In this section, we’ll replace our hard-coded set of IssueRow components with a programmatically generated set of components from an array of issues. In later chapters we’ll get more sophisticated by fetching the list of issues from a database, but for the moment, we’ll use a simple in-memory JavaScript array to store a list of issues.

You can add more example issues, but two issues are enough to demonstrate dynamic composition. Now, let’s modify the IssueTable class to use this array of issues rather than the hard-coded list. Within the IssueTable class’ render() method, let’s iterate over the array of issues and generate an array of IssueRows from it.

In other frameworks and templating languages, creating multiple elements using a template would have required a special for loop construct (e.g., ng-repeat in AngularJS) within that templating language. But in React, regular JavaScript can be used for all programmatic constructs. This not only gives you the full power of JavaScript to manipulate templates, but also a lesser number of constructs to learn and remember.

Now, we can remove rowStyle from all the table-cells and table-headers. One last thing that needs to be done is to identify each instance of IssueRow with an attribute called key. The value of this key can be anything, but it has to uniquely identify a row. React needs this key so that it can optimize the calculation of differences when things change, for example, when a new row is inserted. We can use the ID of the issue as the key, as it uniquely identifies the row.

After these changes, the screen should look like Figure 3-6.

Summary

In this chapter, we created a barebones version of the main page of the Issue Tracker. We started using React classes instead of simple elements, some of which were just placeholders to depict components that we have not yet developed. We did this by writing fine-grained individual components and putting them together (composing) in an enclosing component. We also passed parameters or data from an enclosing component to its children, and thus reused a component class and rendered it differently with different data, dynamically using a map() to generate components based on an array of input data.

The components didn’t do much apart from rendering themselves based on the input data. In the next chapter, we’ll see how user interaction can affect the data and change the appearance of a component.

Answers to Exercises

Initial State

The state of a component is captured in a variable called this.state in the component’s class, which should be an object consisting of one or more key-value pairs, where each key is a state variable name and the value is the current value of that variable. React does not specify what needs to go into the state, but it is useful to store in the state anything that affects the rendered view and can change due to any event. These are typically events generated due to user interaction.

For the IssueTable component, the list of issues being displayed is definitely one such piece of data that both affects the rendered view and can also change when an issue is added, edited, or deleted. The array of issues is therefore an ideal state variable.

Other things, such as the size of the window, also can change, but this is not something that affects the DOM. Even though the display changes (for example, a line may wrap because the window is narrower), the change is handled by the browser directly based on the same DOM. So, we don’t need to capture this in the state of the component. There may be cases where it does affect the DOM; for example, if the height of the window determines how many issues we display, we may store the height of the window in a state variable and restrict the number of IssueRow components being constructed. In those cases, the height of the window, or a derived value, for example, the number of issues being shown, could also be stored in the state.

Things that don’t change, for example, the border style of the table, also don’t need to go into the state. That’s because user interaction or other events do not affect the style of borders.

Note that we used only one state variable called issues. We can have other state variables, for instance if we were showing the issue list in multiple pages, and we wanted to also keep the page number currently being shown as another state variable, we could have done that by adding another key to the object like page: 0.

Running and testing this piece of code should show no change in the application; you will still see a table containing two rows of issues, just as before.

Async State Initialization

Although we set the initial state in the constructor, it is highly unlikely that regular SPA components will have the initial state available to them statically. These will typically be fetched from the server. In the case of the Issue Tracker application, even the initial list issues to be displayed would have to be fetched via an API call.

If there were additional state variables, setting only one variable (issues) will cause it to get merged with the existing state. For example, if we had stored the current page as another state variable, the new value of the state variable issues will be merged into the state, keeping the value of the current page unchanged.

The timeout value of 500 milliseconds is somewhat arbitrary: it’s reasonable to expect a real API call to fetch the initial list of issues within this time.

Now, it is very tempting to call loadData() within the constructor of IssueTable. It may even seem to work, but the fact is that the constructor only constructs the component (i.e., does all the initialization of the object in memory) and does not render the UI. The rendering happens later, when the component needs to be shown on the screen. If this.setState() gets called before the component is ready to be rendered, things will go awry. You may not see this happening in simple pages, but if the initial page is complex and takes time to render, and if the Ajax call returns before rendering is finished, you will get an error.

If you refresh the browser (assuming you’re still running npm run watch and npm start on two different consoles), you will find that the list of issues is displayed as it used to be in the previous steps. But, you will also see that for a fraction of a second after the page is loaded, the table is empty, as shown in Figure 4-1.

It gets filled soon after, but still, there is a flicker. When we explore server-side rendering in later chapters, we will get rid of this ungainly flicker. For the moment, let’s live with this minor UI unpleasantness.

Updating State

In the previous sections, you saw how to set the initial state, using a direct assignment in the constructor as well as setting a value in other lifecycle methods using this.setState(). In this section, let’s make a minor change to the state rather than set a completely new value to it. Let’s add a new issue and thus change, not the complete state, but only a portion of it.

It may seem to work, but it will have unexpected consequences in some of the lifecycle methods within this as well as descendent components. Especially in those methods that compare the old and new properties, the difference between the old state and the new one will not be detected.

What is needed in the setState() call is a fresh array of issues, say a copy of the state variable. If any existing array element, say an issue itself, is changing, not only is the copy of the array needed, but also the copy of the object that is being changed is needed. There are libraries called immutability helpers, such as immutable.js ( http://facebook.github.io/immutable-js/ ), which can be used to construct the new state object. When a property of the object is modified, the library creates a copy optimally.

But we will only append an issue, and not change an existing issue. It’s fairly straightforward to make a shallow copy of the array, and this will suffice for the moment. So, we won’t be using the library—there isn’t much extra code we need to write to handle it. If, in your application, you find that you have to make lots of copies because of deep nesting of objects in the state, you could consider using immutable.js.

On running this set of changes and refreshing the browser, you’ll see that there are two rows of issues to start with. After two seconds, a third row is added with a newly generated ID and the contents of the sample issue. A screenshot of the three-row table is shown in Figure 4-2.

Note that we did not explicitly call a setState() on the IssueRow components. React automatically propagates any changes to child components that depend on the parent component’s state. Further, we did not have to write any code for inserting a row into the DOM. React calculated the changes to the virtual DOM and inserted a new row.

At this point, the hierarchy of the components and the data flow can be visually depicted, as shown in Figure 4-3.

Lifting State Up

Before we add user interface elements to create new issues, let’s move the initiation of the creation to where it really belongs: in the IssueAdd component. This will allow us to deal with the changes one step at a time, because moving the timer for adding a new issue from the IssueTable component to the IssueAdd component is not as trivial as it first appears.

If you do try to move it, you will immediately realize that the createIssue() method will also have to move, or we need to have a variant within IssueAdd that can communicate back to IssueTable and call the createIssue() method, which continues to remain there. But there is no straightforward way to communicate between siblings in React. Only parents can pass information down to children; horizontal communication seems hard, if not impossible.

The way around this is to have the common parent contain the state and all the methods that deal with this state. By lifting the state up on level to IssueList, information can be propagated down to IssueAdd as well as to IssueTable.

We still have to take care of one more thing before we can say we are done with this set of changes. All this while, we have been using the arrow function syntax to set up timers. In ES2015, the arrow function has the effect of setting the context (the value of this) to the lexical scope. This means that this within the callback will refer to whatever this was in the lexical scope, that is, outside of the anonymous function, where the code is present.

That worked as long as the called function was within the same class as the timer callback. It still works, in the loadData() method, because this refers to the IssueList component where the timer was fired, and therefore, this.state refers to the state within IssueList itself.

But, when createIssue is called from a timer within IssueAdd, this will refer to the IssueAdd component. But what we really want is for createIssue to be always called with this referring to the IssueList component. Otherwise, this.state.issues will be undefined.

But then, if we need to ever refer to the same method again and pass it to some other child component, we’d have to repeat this code. Also, there is never going to be a case where we will need the method to be not bound, so it is best to replace the definition of createIssue with a bound version of itself. The recommended way to do this is in the constructor of the class where this method is implemented.

The effect of these changes will not be seen in the user interface. The application will behave as it used to. On refreshing the browser, you will see an empty table to start with, which will soon be populated with two issues and after two seconds, another issue will be added.

But this sets us up nicely for the change where we can replace the timer in IssueAdd with a button that the user can click to add a new issue.

Event Handling

Let’s now add an issue interactively, on the click of a button rather than use a timer to do this. We’ll create a form with two text inputs and use the values that the user enters in them to add a new issue. An Add button will trigger the addition.

If you run the code, you’ll see a form being displayed in place of the placeholder in IssueAdd. The screenshot of how this looks is shown in Figure 4-4.

At this point, clicking Add will submit the form and fetch the same screen again. That’s not what we want. Firstly, we want it to call createIssue() using the values in the owner and title fields. Secondly, we want to prevent the form from being submitted because we will handle the event ourselves.

To handle events such as onclick and onsubmit, the properties that we need to supply to the elements are, simply, onClick and onSubmit. As in plain HTML and JavaScript, these properties take functions as values. We’ll create a class method called handleSubmit() to receive the submit event from the form when the Add button is clicked. Within this method, we’ll need a handle to the form, so as in regular HTML, let’s give the form a name, say, issueAdd which can then be referred to in JavaScript using document.forms.issueAdd.

You can now test the changes by entering some values in the owner and title fields and clicking Add. You can add as many rows as you like. If you add two issues, you’ll get a screen like the one in Figure 4-5.

At the end of all this, we have been able to encapsulate and initiate the creation of a new issue from the IssueAdd component itself. To do this, we “lifted the state up” to the least common ancestor, so that all children have access to it directly via passed-in props or via callbacks that can modify the state. This new UI hierarchy data and function flow is depicted in Figure 4-6. Compare this with the situation where the state was maintained in IssueTable, as in Figure 4-3.

Stateless Components

We have three functioning React components (IssueAdd, IssueRow and IssueTable) composed hierarchically into IssueList (another one, the IssueFilter, is still a placeholder). But there is a difference among these functioning component classes.

IssueList has lots of methods, a state, initialization of the state, and functions that modify the state. In comparison, IssueAdd has some interactivity, but no state¹. But, if you notice, IssueRow and IssueTable have nothing but a render() method. For performance reasons and for clarity of code, it is recommended that such components are written as functions rather than classes: a function that takes in props and just renders based on it. It’s as if the component’s view is a pure function of its props, and it is stateless. The render() function itself can be the component.

Designing Components

Most beginners will have a bit of confusion between state and props, when to use which, what granularity of components should one choose, and how to go about it all. This section is devoted to discussing some principles and best practices.

Summary

In this chapter, you learned how to use state and make changes to it on user interactions or other events. The more interesting aspect was how state values are propagated down the component hierarchy as props. You also had a glimpse of user interaction: the click of a button to add a new issue, and how that causes the state to change, and in turn, how the props in the descendant components changed, causing them to rerender as well. Further, you learned how a child can communicate with its parent via callbacks.

We used simulated asynchronous calls and data local to the browser to achieve all this. In the next chapter, instead of using local data, we’ll fetch the data from the server. When an issue is added, we’ll send the data to the server to persist it.

Answers to Exercises

Express

I briefly touched upon Express and how to serve static files using Express in the Hello World chapter. But Express can do much more than just serve static files. Express is a minimal, yet, flexible web application framework. It’s minimal in the sense that by itself, Express does very little. It relies on other modules called middleware to provide the functionality that most applications will need.

REST API

REST (short for representational state transfer) is an architectural pattern for application programming interfaces (APIs). There are other older patterns such as SOAP and XMLRPC, but of late, the REST pattern has gained popularity.

Since the APIs in the Issue Tracker application are only for internal consumption, we could use any API pattern or even invent our own. But let’s not do that because using an existing pattern forces you to think and organize the APIs and schema better and encourages some good practices.

Although we won’t be using the REST pattern, I’ll discuss it briefly since it is one of the more popular choices due to its simplicity and small number of constructs. It’ll let you appreciate the differences and the logic for the choice that I’ll make eventually, to use GraphQL.

GraphQL

Although the REST paradigm is quite useful in making APIs predictable, the shortcomings discussed previously have made it hard to use it when different clients access the same set of APIs. For example, how an object is displayed in a mobile application and the same is displayed in a desktop browser can be quite different, and therefore, a more granular control as well as aggregation of different resources may work better.

GraphQL was developed to address just these concerns. As a result, GraphQL is a far more elaborate specification, with the following salient features.

The About API

Let’s start with a simple API that returns a string, called About. In this section, we’ll implement this API as well as another API that lets us change the string that is returned by this API. This will let you learn the basics of simple reads as well as writes using GraphQL.

For the About API, we don’t need any special types, just the basic data type String is good enough. But GraphQL schema has two special types that are entry points into the type system, called Query and Mutation. All other APIs or fields are defined hierarchically under these two types, which are like the entry points into the API. Query fields are expected to return existing state, whereas mutation fields are expected to change something in the application’s data.

A schema must have at least the Query type. The distinction between the query and mutation types is notional: there is nothing that you can do in a query or mutation that you cannot do in the other. But a subtle difference is that whereas query fields are executed in parallel, mutation fields are executed in series. So, it’s best to use them as they are meant to be used: implement READ operations under Query and things that modify the system under Mutation.

In addition to specifying the type, the Schema Language has a provision to indicate whether the value is optional or mandatory. By default, all values are optional (i.e., they can be null), and those that require a value are defined by adding an exclamation character (!) after the type.

Note that all arguments must be named. There are no positional arguments in the GraphQL Schema Language. Also, all fields must have a type, and there is no void or other type that indicates that the field returns nothing. To overcome this, we can just use any data type and make it optional so that the caller does not expect a value.

Note that I stopped calling these APIs, rather I am calling even something like setAboutMessage a field. That’s because all of GraphQL has only fields, and accessing a field can have a side effect such as setting some value.

The next step is to have handlers or functions that can be called when these fields are accessed. Such functions are called resolvers because they resolve a query to a field with real values. Although the schema definition was done in the special Schema Language, the implementation of resolvers depends on the programming language that we use. For example, if you were to define the About API set, say, in Python, the schema string would look the same as in JavaScript. But the handlers would look quite different from what we are going to write in JavaScript.

As I pointed out earlier, GraphQL schema and introspection allows tools to be built that can let developers explore the API. The tool called Playground is available by default as part of the Apollo Server and can be accessed simply by browsing the API endpoint. Thus, if you type http://localhost:3000/graphql in your browser’s URL bar, you’ll find the Playground UI.

The default for the Playground is a dark theme. Using the settings function (gear icon in the top-right corner), I have changed it to a light theme as well as reduced the font size to 12. If you also make these changes, you may see the UI as shown in Figure 5-1.

Before we test the APIs, it’s a good idea to explore the schema using the green SCHEMA button on the right side of the UI. On doing that, you’ll find that the about and setAboutMessage fields are described in the schema. To make a query, you can type the query in the left-side window and see the results on the right side after clicking on the Play button, as described in the UI.

Note that there is an autocompletion feature in the Playground, which may come in handy as you type. The Playground also shows errors in the query using red underlines. These features use the schema to know about the available fields, arguments, and their types. The Playground queries the schema from the server, so whenever the schema changes, if you rely on autocompletion, you need to refresh the browser so that the changed schema is retrieved from the server.

The output is a regular JSON object unlike the query, which followed the query language syntax. It also reflects the structure of the query, with "data" as the root object in the result.

Now, running the original about query (in the first tab) should return the new message, "Hello World!" to prove that the new message has been successfully set in the server. To assure ourselves that there is no magic that the Playground is doing, let’s also run a query using cURL on the command line for the about field.

GraphQL Schema File

In the previous section, we specified the GraphQL schema within the JavaScript file. If and when the schema grows bigger, it would be useful to separate the schema into a file of its own. This will help keep the JavaScript source files smaller, and IDEs may be able to format these files and enable syntax coloring.

There’s just one other thing that needs a change: the nodemon tool that restarts the server on detecting changes to files by default only looks for changes to files with a .js extension. To make it watch for changes to other extensions, we need to add an -e option specifying all the extensions it needs to watch for. Since we added a file with extension .graphql, let’s specify js and graphql as the two extensions for this option.

If you restart the server using npm start now , you will be able to test the APIs using the Playground and ensure that they behave as before.

The List API

Now that you have learned the basics of GraphQL, let’s make some progress toward building the Issue Tracker application using this knowledge. The next thing we’ll do is implement an API to fetch a list of issues. We’ll test it using the Playground and, in the next section, we’ll change the front-end to integrate with this new API.

Now, let’s add a new field under Query to return a list of issues. The GraphQL way to specify a list of another type is to enclose it within square brackets. We could use [Issue] as the type for the field, which we will call issueList. But we need to say not only that the return value is mandatory, but also that each element in the list cannot be null. So, we have to add the exclamation mark after Issue as well as after the array type, as in [Issue!]!.

In the server code, we need to add a resolver under Query for the new field, which points to a function. We’ll also have an array of issues (a copy of what we have in the front-end code) that is a stand-in for a database. We can immediately return this array from the resolver. The function could be in-place like that for the about field, but knowing that we’ll expand this function to do more than just return a hard-coded array, let’s create a separate function called issueList for it.

To test this in the Playground, you will need to run a query that specifies the issueList field, with subfields. But first, a refresh of the browser is needed so that the Playground has the latest schema and doesn’t show errors when you type the query.

The array itself need not be expanded in the query. It is implicit (due to the schema specification) that issueList returns an array, and therefore, subfields of the field are automatically expanded within the array.

If you add more subfields in the query, their values will also be returned. If you look at the date fields, you will see that they have been converted from a Date object to a string using the toString() method of the Date JavaScript object.

List API Integration

Now that we have the List API working, let’s get it integrated into the UI. In this section, we will replace the implementation of the loadData() method in the IssueList React component with something that fetches the data from the server.

We will also need to add the keyword async for the function definition of loadData() since we have used awaits within this function.

That completes the changes required for integrating the List API. Now, if you test the application by refreshing the browser, you will find a screen similar to the screenshot shown in Figure 5-2. You will notice that the dates are long and ungainly, but otherwise, the screen looks the same as it did at the end of the previous chapter. An Add operation will not work, because it uses Date objects rather than strings when adding a new issue. We will address these two issues in the next section.

Custom Scalar Types

Storing dates as strings may seem to work most times, but not always. For one, sorting and filtering on dates makes it harder, because one has to convert from string to Date types every time. Also, dates should ideally be displayed in the user’s time zone and locale, regardless of where the server is. Different users may see the same dates differently based on where they are, and even see dates in the form of "2 days ago" etc.

To achieve all that, we need to store dates as JavaScript’s native Date objects. It should ideally be converted to a locale-specific string at the time of displaying it to the user only. But unfortunately, JSON does not have a Date type, and thus, transferring data using JSON in API calls also must convert the date to and from strings.

The recommended string format for transferring Date objects in a JSON is the ISO 8601 format. It is concise and widely accepted. It is also the same format used by JavaScript Date’s toJSON() method. In this format, a date such as 26 January 2019, 2:30 PM UTC would be written as 2019-01-26T14:30:00.000Z. It is easy and unambiguous to convert a date to this string using either the toJSON() or the toISOString() methods of Date, as well as to convert it back to a date using new Date(dateString).

Two other methods, parseValue() and parseLiteral(), are needed to parse strings back to dates. Let’s leave this parsing to a later stage when it is really needed for accepting input values, since these are optional methods.

Now, in App.jsx, we can convert the string to the native Date type. One way to do this is to loop through the issues after fetching them from the server and replace the fields due and created with their date equivalents. A better way do this is to pass a reviver function to the JSON parse() function. A reviver function is one that is called for parsing all values, and the JSON parser gives it a chance to modify what the default parser would do.

With this set of changes, the application should appear as before, at the end of the previous chapter. The dates will look nicely formatted. Even adding an issue should work, but on refreshing the browser, the added issue will disappear. That’s because we have not saved the issue in the server—all we have done is changed the local state of the issue list in the browser, which will be reset to the initial set of issues on a refresh.

The Create API

In this section, we will implement an API for creating a new issue in the server, which will be appended to the list of issues in the server’s memory.

To do this, we have to first define a field in the schema under Mutation called issueAdd. This field should take arguments, just as the setAboutMessage field did. But this time, we need multiple arguments, one for each property of the issue being added. Alternatively, we can define a new type as an object that has the fields we need for the input. This can’t be the same as the Issue type because it has some required fields (id and created) that are not part of the input. These are values that are set by the server only. Further, GraphQL needs a different specification when it comes to input types. Instead of using the type keyword, we have to use the input keyword.