NodeJS and ShimmerCat work great together

NodeJS + ShimmerCat

If you are a JavaScript end-to-end developer you can use ShimmerCat's API domains to serve the dynamic bits of your application while using electric domains to serve the static assets.

This guide shows how to setup the two parts of a very basic NodeJS application, front-end and back-end, so that they can communicate through ShimmerCat.

The advantages of using ShimmerCat at development, vs using the bare-bones server is that you get to see your site from minute five using *https://, your intended final Internet domain and HTTP/2. Also you can share your web project setup more easily with fellow team developers.

The complete project can be found at Github.

Starting out

As usual, we recommend that you create a folder for your project

$ mkdir nodejs_project
$ cd nodejs_project

You will need ExpressJS

We are using ExpressJS for this project. You can install it as they recommend in their website:

$ npm install express --save

You may of course install ExpressJS in any other way, we are providing the steps only for completeness sake.

Using separate folders

Even the simplest web project will quickly benefit from having source and generated files in separate folders. Therefore we are going to do that for our front-end code. Our source folder will be called client-src, and our folder with generated code will be client-bin. The contents of the first can be assimilated into version control (e.g., processed with git add), while the second folder should be ignored by version control. For more details, please have a look to the .gitignore file.

$ mkdir client-bin client-src

All the code for the NodeJS application will be at the folder server.

$ mkdir server

The code

The code for the front-end

Our file index.html is very simple:

<!doctype html>
<html lang=en>
...
    <span id="button1">Click me!</div>
    <script src="/js/jquery.js"></script>
    <script src="/js/app.js"></script>
....
</html>

We simply define some styles, and a button which we name button1. Then we load JQuery and an application script. This .html file, and also the JavaScript file it references, should be stored at a electric domain. We will describe the corresponding devlove.yaml file in a bit.

You can obtain the JQuery library at the usual places, and it is also included in our project repository.

That leaves us with the application script /js/app.js. Here is how it looks:

(function (){

function whistle()
{
  var post_promise = $.post(
    "https://myapi.express-website.mine/whistle-point/",
    {
      msg: 'User clicked button 1!'
    }
  );

  post_promise.then(function(){
    $("#button1").text("You have been successfully reported");
  })
}

function install_handlers()
{
  $("#button1").click(whistle);
}

$(document).ready(install_handlers);

})();

The above script takes care of sending a POST request whenever the user clicks the span which we have named #button1. This source script goes at the client-src folder.

Take note of the domain to which we make the POST request. We will be running the NodeJS API end-point behind that host name. But thanks to the magic of SOCKS5, there is no need to worry about configuring that domain name.

JavaScript code for the server

For the server, all we are going to do is serve the requests. Therefore, the code is pretty simple:

var express = require('express');
var app = express();

// respond with "hello world" when a GET request is made to the homepage
app.post('/whistle-point/', function(req, res) {
  console.log("Somebody pressed the button");
  res.send('User properly reported');
});

app.listen(8000, function () {
  console.log('Reporting backend listening in port 8000');
});

Just keep note of the port, we will need for the next part

The server configuration file.

In the root of your directory, create a text file named devlove.yaml with the following contents:

---
shimmercat-devlove:
    domains:
        www.express-website.mine:
            root-dir: client-bin
        myapi.express-website.mine:
            port: 8000

In the example above, note the use of the website names, the root directory client-bin for the electric domain, and the port number.

The contents of this file describe two virtual domains. The first one, www.express-website.mine is the electric domain holding your application assets, and the second one is the API domain where you put the NodeJS application to listen.

Building the project

For any non-trivial application you would also need a build pipeline. Here, we are going with the simplest solution: a bash script that copies from client-src to client-bin:

echo "Copying JS files"
mkdir -p "client-bin/js/"
cp client-src/index.html client-bin/index.src
cp client-src/js/app.js client-bin/js/app.js
cp client-src/js/jquery.js client-bin/js/jquery.js

Running the back-end and the server

You need to run ShimmerCat and your application simultaneously. In a production environment you would probably want to use some kind of application supervision program, but for development one of the most straightforward ways to go is to use two terminals. Just be sure to have both terminals at your project folder (we named it nodejs_project at the beginning of this guide).

In one of the terminals you leave ShimmerCat running:

$ shimmercat devlove

in the other you run your NodeJS application:

$ node server/app.js

Accessing the new site

Now you can fire a browser, e.g., Chrome:

$ sc-tool chrome

and in the browser's navigation bar, just type (please beware of the "https://" prefix!) https://www.express-website.mine/ and press ENTER. If you want to understand better what we are doing, you can check our page on easy networking (for developers) with a SOCKS5 proxy.