This tutorial will take you through the steps of building a web app supported by the Node.js JavaScript runtime, and deploying it to the web on the Heroku platform. In this tutorial you'll build a simple score sheet that takes new scores and names from user-input and displays them on a web-page, keeping a persistent log of user-additions in a .json file. This will take you through all of the steps of initializing an app, building folder architecture, writing paths for your server, testing and deploying. You can find the example app files here, and see a version running on Heroku here.

This tutorial was written working with videos and code from Dan Shiffman.

Building the App

At this point, you'll want to build out the front end of your application: the index.html and style.css files in the "public" folder. This is the public facing side of your application, or the files that the server will serve. In other words, when someone navigates to the web address where your application sits, this is the index.html that will load, the styles that will be applied, and the javascript that will be run.

The server (server.js which will sit at the project root) itself will also be written in JavaScript, so you should not get these two files confused. If you plan on making a p5.js canvas for your front end, the code for this would sit in the .js file in "public", and this file would be called by your index.html page. This JavaScript file will also contain "get" and "post" calls to your server. Think about this when designing your app. What data do you want to send to the server? What data do you want to receive?

In the example, data is input by the user of the frontend in the input fields, and then that data is sent to the server. Right now, when designing the front end, I will need to add these input fields, and write code in the .js file to grab data from these fields when the user submits it.

Check out app.js. This file is written in JavaScript using p5.js. in the setup() function I've written code to select the inputs and reference them to a variable and to create a "submit" button.

When the submit button is pressed, the submitData() function is called which grabs the values in the input fields, and runs a "GET request" with the p5.js function loadJSON() . Writing what happens when these get requests are called will happen on the server side, but for now just note that the important part happens with the parameters entered into loadJSON() , which structure a url extension with the name and score entered by the website user in the input fields. When this function is finished a callback is called that runs two other functions, clearTheP(), which removes the previous scores div from the page, and drawData(), which pulls all of the data from the server and displays it on the page.

drawData() and its callback function, gotData() do the work of calling the stored scores back from the server and displaying these on the page. Like the function to submit data, drawData() also uses the loadJSON() method in p5. Note that in this function, the path that the function is loading is simply 'all'. gotData() then parses through the data and displays the scores in a div of p elements.

Some things to note at this point:

• This javascript file will interact with the server using entirely "get" requests. These are easy to make because we can add our data to url strings. Since each data call is only to add one name and one score, the data to be sent is tiny and can be sent by adding these variables into a url path (making these url paths is how a get request works). If you need to be able to send a lot of data you'll want to use a POST request, which is slightly different. There is a method for this in p5 called httpPost(), which should help you send larger JS objects formatted as JSON. You can also see an example a post request in my twitterPhotoBooth demo.
• We're using loadJSON() because it is easy, and we're working with JSON formatted data. P5.js also has a method for httpGet(), which could be used in a similar way to loadJSON() here, formatting the URL as a query string as in the example above (eg:"/name/score").
• These methods for getting and posting are native to P5.js, and in vanilla JavaScript things are a bit more complicated. JQuery and JavaScript both support various methods for get and post. There is a good article on these here

At this point, you should also finish the html and css for your demo. Next you'll write the server.

Writing the Routes for Server.js

Writing the server starts with importing the node packages ("modules") you'll need for support. Node makes this a simple command line process. This project will use one external package called express, which will provide methods for writing the GET Routes for the server. Here's the Express Documentation.

Open up a Terminal window and navigate back to your main project folder. Once you're in there (you can always check where you are with the command "pwd"), enter the following into your command line:

The "sudo" prefix stands for "super-do", and will require you to enter your password. You may not need this command depending on the user settings on your computer, but it's safe to use it here. The "npm install express" is the command to install express, and the "--save" suffix tells the installer to write this "dependency" to the package.json file. You package.json file should now be updated to include this dependency, and you will have a new "node modules" folder in your project folder.

In your main project folder, the folder that CONTAINS the "public" folder, create a file called server.js. This file will contain the code for your server, and so it needs to sit in the project "backend" outside of public. Your folder structure should look something like this:

In the server.js file you're now ready to create the server.

Start with this:

I'll run through each part, line-by-line:

• var express = require('express'); and var app = express(); load the express package (it's in the node modules folder now, but node knows where to find it), and create an instance of it in the variable app. From now on, when you want to do things with express methods like .use() or .get(), you'll hook it to app, as in app.use().
• The command to start the server and listen to a port is on line 13: var server = app.listen(process.env.PORT || 5000, listen);. The syntax is structured precisely for uploading to Heroku, but this will also work for local development and start your server to serve things at port 5000 or http://localhost:5000. The "port" is an endpoint for messages. This is like opening a channel for your server to communicate with the frontend which will be displayed in a browser.
• function listen() is the callback for the function above. This just logs the server and port so you have easy access to the address. The console.log() logs this to the console (your Terminal application, in this case) so you can easily copy/paste the local web address once the server has started.
• The next command on line 25 actually points your app towards the public folder. app.use(express.static('public')); Tells the server to serve up the contents of the public folder.

Create your first server.js with just these lines, save your server.js file and navigate to the Terminal. Make sure you're in your main project folder, where server.js sits (run the command "ls" to list the contents of your current directory). And run the following command:

Hit enter - this is the command to start the server. You should see this in the Terminal:

Your server has started!

Navigate to http://localhost:5000 to see the contents of index.html. With this server.js file you've created a pretty decent development server. You don't have any server "paths" yet, or real directed communication between the server and your frontend. But you could now write an app.js file in the public folder that can preload image and sound files, make api calls to load data from the web, and do other things for development that are not possible without a background server running. And you could use this as a development server to create a website, add folders, HTML, CSS and JS files to public, and create links between these files.

At this point, it's time to write some server paths. These will work just like url paths from the frontend, but a little differently than the ones we have been creating to web addresses serving html files or hosting media. In the front end app.js file, the functions to submit and get data construct url "paths" to be executed with loadJSON(). For example, submitData(); constructs a url path that looks like /add/name/score, and pulls data for "name" and "score" from the user input fields. That code creates a url that looks like http://localhost:5000/add/max/30, and executes that path with loadJSON();. On the server side, instead of having that path serve up an .html file, it will trigger a function that will execute any time that path is followed, and it will grab and store that data - in the case of the example path it would save "max" and "30" as a new name and score. You can use paths like GET and POST to do any number of things: send data to the server (as in this example) load data from the server (also in this example), make an API call, trigger another server process, etc. This structure of paths that execute server processes and pass data back and forth is the foundation of back-end development. It can happen in any number of languages (Ruby, PHP, JAVA). Here, you're doing it with JavaScript in the node.js framework.

You'll now have to write the "GET" paths for the server to follow.

The syntax for that looks like this:

Add these lines to your file, go to the Terminal, make sure you're in the right directory and restart the server in the terminal with:

Hit enter. Open a browser window and navigate to http://localhost:5000/myPath. You should see this in your browser window:

Take a look again at the server code in server.js. app.get(); has two parameters: 1) the path to follow, in this case "/myPath", and 2) the callback function, in this case function executeWhenPathIsFollowed(), which has a purposefully convoluted name to make a point. This is your first server path. As long as this line is in your code, anytime someone navigates to /myPath from your server root, they'll get a short text response displayed in the browser.

Now to set up the first real path that actually grabs some data. In the frontend, you wrote a path that looked like /add/name/score. In the backend, we're going to get the contents of the path as our data. Add the following app.get() and callback function to your server:

This tells the server where to go when /add/name/score is followed from the frontend. Notice the : in front of both name and score, and the ? following score. This means that the server is expecting these as "parameters" of the request, and the question mark at the end will allow the path to leave score off, and still work.

The newEntry(request,response) function has two parameters, as above, request and response. (any GET or POST path you write will have request and respose parameters) The request will carry the path's "data". The response will send back a response to the browser.

Stop your server, save server.js and restart in the Terminal, then navigate to http://localhost:5000/add/jane/55

In the browser window, you should see the response from the server: "Thank you for your addition, Jane. Your score was: 55"

In practice you'll want to actually have the server store this data and do something with it, not just display it in the browser window. Node.js has several modules for handling getting and storing data in files. One of these is "fs" or FileSync, and this comes native with node.js and does NOT have to be installed with npm install ___.

Add the following line to server.js to "require" the fs module:

At this point, you're going to set up a sort of "dummy" database that will exist in your server and store the score data in the form of a .json file, the file that you'll be "synching" with FileSync.

Navigate over to Brackets or whatever your code editor you're using and create a new file called "scores.json". In that file, write your first object of data, just to start the server off with something when it reads this file for the first time:

Save this file, and in server.js, add some lines to load and read this file and store its contents in the variable scores when the server starts.

Now, anytime you start the server, you'll load the scores.json file and store it in the scores variable. You'll be able to both update and save new scores using this variable as the program is running.

Now, re-write the /add/:name/:score? path callback to actually do something with that data when it's received in the path.

In server.js, you're going to update the function newEntry(request,response).

The new version of that function should look like this:

Step by step through this code:

• request.params is where the necessary data will come through the path. The name and score coming in through /add/:name/:score? are stored in the name and score variables.
• Number() helps to make sure the score is actually a number (in case you want to do something with this fact later: sort the data, etc.)
• A variable is created for the reply that will be sent back to the client.
• Then, some conditional logic handles the data storage. First, if there's no score, don't store the data and send back a reply asking for a score.
• If there's a score, it's added to the scores object with scores[name] = score. This makes each score in the object a key - value pair with the name as the key and the numerical score as the value. You could format this in many ways depending on your use-case before saving to .json. Remember: on the other end, when the data comes back to display client-side, app.js will also have to read this data in whatever way you format it here.
• var data = JSON.stringify(scores, null, 2) uses the JavaScript method JSON.stringify(). The parameters here are JSON.stringify(obj, replacer, white space).
• Finally fs.writeFile('scores.json', data, finished) writes the data to the file scores.json, and then calls the callback function finished() where the final reply to the client is formatted and sent.
• Note that the scores JavaScript Object is sent back to the client in the response with var reply = {msg: "thanks for adding your score", newScores: scores} and response.send(reply);

You can now test this out by starting your server again in the terminal, and navigating in the browser to http://localhost:5000/add/Bob/33.

You should get back the reply object with the msg, your new entry, and whatever other entries you've added in completing this tutorial.

The final thing to add to the server is a function that simply returns all of the data when the /all path is followed. Add the following at the end of your server.js

This assigns the path to /all to a function that returns the scores object which should be persistently updated to reflect any new scores. Again, stop your server, start it again, and check the new path by going to http://localhost:5000/all. You should get a response in the browser with the entire scores object.

Even without the frontend, you now have a basic API for your scores data with two paths: one to add new names and scores, and one to show all of the data in the "database" (the .json and javascript object where the scores data are stored).