The goal of this blog post is to teach you how to build a very smooth web application that will require close to zero configuration and that you will be able to publish on the Node Package Manager.
Initially I performed this tutorial as a talk in front of an audience. It doesn't take more than 30 minutes to cover it fully including development, publishing, installation and running of the app.

Why this tutorial?

Web development requires too much configuration
Sharing a web app is too complex.
There is not enough complete tutorial about single-page app development.

What will you find?

This how-to will lead you to build a minimalist bookmark manager application. It is splitted in four parts:

Description of the main concepts of single page applications

We cover the client part before the server part. That way, we start from the requirements. Beginning from the data model could lead to useless features.

Why Single-Page apps?

NB: In the following we'll use the SPA acronym in place of Single-Page Apps.

Here are the key benefits of a SPA:

Better user experience: it feels more like a native application. By avoiding repetitive reloading it makes transitions smoother than with traditional web apps.
Less network consumption: it only loads the required data, not the full HTML markup.
Better application architecture: you can build modular application that are more maintanable (parts are less tighted and can be modified or replaced without impacting the rest).
The server is only a REST API: it allows to build any kind of client like a command line tool, a real native application, etc.

What a single-page app is made of?

Single-page applications are made of:

a client: one HTML page and lot of JavaScript.
a web server: basically a REST API

The client

The client is made only of Javascript. The full GUI is developed in the browser. It requests the server only when it requires data, persists data or to run a specific operation.

Displaying (rendering)

To build the user interface, SPA use the DOM, the technology that renders the HTML to the screen and maintains its state. Instead of sending a prebuilt HTML page to the browser, the SPA will send a minimalistic HTML page that will load a big javascript application. That app will run series of Javascript instructions to modify the DOM. It will display the user interface. That way, the user will be able to interact with the server through this GUI.

Reacting (event management)

Displaying things is nice but with SPA, we do not only show informations, we want to interact with the user. Fortunately, the DOM provides an event system. Javascript applications can listen to this events. This is the key of the user interactions.

Let's take a simple example. In the render step, we display a button. We add a click listener to this button and attach a function to it. So, when the user will click on the button, the function will be executed. In this function we can modify the DOM or popping an alert: it will send to the user a feedback when he clicks. It means that the application will react to user changes.

A more complex example that involved the server:
The user clicks on the button and the listener function is executed. The function displays a loading spinner aside the button. It sends a request to the server. Once it gets the answer, it hides the spinner and displays the result of the request.

Technology involved: ReactJS

React is a technology that allows to manage the rendering of view component in an expressive way. React will allow us to link a state (a javascript object) to a rendering function. We will only have to manage properly the state of the component to provide the user with changes. Rect don't require to think much about the architecture of an application to build simple components that works together.

Here are a few other reasons for the choice of React:

It's trendy
It allows to do simple ui quickly (no need to understand what is MVC)
It allows to create reusable components that you can share via NPM too

Technology involved: Browserify

To run Javascript files, the browser requires to load them one by one. When you write proper code you have many files involved and it's painful to load them all in the browser. That's why we need a tool to deal with that.

Browserify will allow us to consider the client as a traditional Node.js app. Through it, we'll be able to declare a manifest. It will handle properly all the required dependencies. Moreover, it will deal with all the build operations to make a single JS file from our code files and from the dependencies. Only this file will be fetched by the browser to run the entire application.

The server (REST API)

The server will be a traditional web app that deal only with JSON. Instead of sending HTML page and consuming forms, it will parse request bodies made of JSON and send responses as JSON objects or arrays.

Every operation handled by the server will be linked with an URL (called route) and a verb (GET, POST, PUT, DELETE). Depending on these two parameters and the request body, the server will perform jobs like creating a new entry or retrieving a set of data. Then the server will build and send a response based on the result of the operation.

Every request sent must follow the HTTP protocol (the one used by every browser). Exceptions are made for websockets. We won't cover it in this tutorial but websockets will basically allow the server to send events to the client. So, the client will be able to react to this event like they were performed by the user. That's particulary useful for realtime updates or collaborative applications.

Technology involved: Node.js

Because we want to make the application publishable on NPM, we'll write it with Javascript for the Node.js platform. Plus, we'll benefit from the many webdev-oriented libs available for Node.js.

Technology involved: Express

To build our server, we will use Express. It's a lightweight web server framework to build simple HTTP APIs. It allows to link routes and verbs to Javascript functions. Every time a route is reached by a request, this function is executed with the request and response objects as parameters. That way it's easy to build a response and send it when we are satisfied with the result ok.

Technology involved: PouchDB

PouchDB is a database that can be embedded in the application. It's an important feature because it will allow us to publish an application that doesn't require any configuration. There is no need to install a database and to setup the connection with the app.

Conclusion

During this first step of the tutorial, we had an overview of what is a single-page app and which technologies we will use. Of course, all this technology require time to be fully understood and mastered. But, it's not required to be an expert to follow this tutorial. In the next steps, we'll introduce you only to the basics. We'll focus on the packaging of the parts to show how to make a working application.

Go read part 2: How to build your client with ReactJS and Browserify

Resources

Build And Share Your Single-page App With React, Node and Pouchdb, part I