The Development Process

In this module, we’ll use Visual Studio Code (VSC) to create a simple app, test it with a browser, create a GitHub repository for our code, and push our code to Heroko so that it accessible to the public.  We’ll use this same process each time we create a new app in this class.

Create a VSC Project

Using the file explorer application that came preloaded on your laptop, create a directory that will hold all of the project files for your app.  You should give the directory a name that is similar to your app name.  For example, in this tutorial we’ll create a simple Hello World app, so a reasonable name for the directory would be something like hello-world.  The location of the directory doesn’t matter, you just have to know where it is.

Next, start VSC.  When you start VCS for the first time you may see a Get Started page.  Click the x in the tab to close it.

Now, on the left side of the app you should see a set of icons.  If you hover over the top one it should say Explorer.  Click on the Explorer icon.  This should display a drop down menu titled NO FOLDERS OPENED.  If you click on the drop down arrow, you should see a button labeled Open Folder.  Click on the Open Folder button and choose the directory that you created for the project.  You should now see the name of your project directory at the top of the Explorer pane.

Set Up Project Directory Structure

Next, we want to create a directory inside our project directory to hold the source code for our app.  There are many ways to create subdirectories in VSC.  One way, in the Explorer pane, is to click on the directory in which you want to create a subdirectory.  This should reveal an icon to create a new Folder (i.e. directory).  If you click on the new Folder icon a text box is revealed in which you can enter the name of the new directory.

Add a subdirectory of your root project folder and name it src.

In future projects, we’ll add many other subdirectories to keep our project organized.

Initialize npm

VSC has a built in terminal application that we can use to issue commands.  You can open the VSC terminal by selecting View -> Terminal from the app’s menubar.  Doing so will open the terminal in a separate pane inside VSC.

If you run the pwd (print working directory) command in the VSC terminal, you should see that your working directory is project’s directory.

$ pwd

Next, we need to set up an npm package for our node application.

To do so, run the following command in the VSC terminal.  When you do, you will be prompted a series of questions.  You can press enter for each to choose the default values.  Before entering yes when asked Is this OK? notice that the value for the main property is index.js.  This is the name of the file that will be executed first when your app runs.  We will change this later.

$ npm init

You can view documentation for all of the npm commands (including init) at https://docs.npmjs.com/cli/v8/commands/.

In the future, to avoid having to press enter for each of the default values, you can simply run the following command to bypass all of the prompts.

$ npm init -y

When you ran npm init, it created a file named package.json.  Open the file and view it’s contents.  This file contains all of the information needed by the node runtime to run the app.

Install npm Packages

Recall that npm packages are libraries of code (often developed by other developers) that we can install in our project and then import and and use in our apps. You can find information about all npm packages at https://www.npmjs.com.

The npm install (or npm i) command downloads and installs into our project a package and any packages that it depends on.

In our Hello World app, we are going to use two packages.  Run the following commands from the VSC terminal to install the nodemon and express packages into your project.

$ npm i nodemon --save-dev
$ npm i express

After you’ve run the commands you should notice that a new subdirectory named node_modules was created in your project. If you expand this subdirectory you will see that the nodemon and express packages were installed in it.  What are all of the other packages?  They are the packages that are dependencies of nodemon and express.  They were installed automatically when nodemon and express were installed.  Open up a few and explore their code.

Per the npm website, “nodemon is a tool that helps develop node.js based applications by automatically restarting the node application when file changes in the directory are detected.”

The –save-dev flag specifies that the package should only be installed when the project is under development or testing, but not when installed on a live environment, like Heroku.

Express is a framework that provides a set of features that make developing web applications quick and easy.  You can view the documentation including guides and their API reference at http://expressjs.com.

If you reopen up package.json you should see two new property; one named devDependencies and another named dependencies.  These properties contain the packages that our app is now dependent on.  So when we push our code to Heroku and Heroku installs our application on their servers, the express package will also be installed, but the nodemon package will not since it is a development dependency.

Write the App

Now let’s write some code.  In the src subdirectory, create a file named app.js and add the following code to it.  Don’t forget to save the file after editing.

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('', (req, res) => {
    res.send('Hello World!')
})

app.listen(port, () => {
    console.log('Server is up on port ' + port)
})

Modify the package.json File

Since our main program is in src/app.js we need to modify the entry point to our web app in package.json.  Modify the main property so that it reads as follows.

 "main": "src/app.js",

Notice the scripts property in package.json.  We want to create two new scripts.  One named start that will run app.js using node, and one named dev that will run app.js using nodemon.

Modify the scripts property so that it reads as follows:

...
"scripts": {
  "start": "node src/app.js",
  "dev": "nodemon src/app.js"
},
...

You can save the file using CTRL + s on Windows and CMD + s on Macs.

Test the Node.js App

Now let’s start up our app using node by issuing the following command. You should see Server is up on port 3000 printed to the terminal.

$ node ./src/app.js

Now open a browser and navigate the browser to http://localhost:3000.  You should see Hello World! in the browser.

Localhost is a reserved hostname refers to the machine on which the client (e.g. the browser) is running from.  Your browser connected to port 3000 on your laptop.  Since your app is listening to port 3000 on your machine, when the browser connected to port 3000, your app responded by sending the browser the text Hello World! 

Stop the app by pressing CTRL + c in the terminal.

Now restart the app by running the npm script named dev by running the following command in the terminal.

$ npm run dev

Verify that the app is running using your browser.

Now change app.js so that the app sends the client some other text other than Hello World and save the file.

Notice that nodemon automatically restarted node.  Use the browser to verify that the app is now sending the new text.

When you’re finished experimenting, shut down the app using CTRL + c.

Create a Git Repository

Let’s create a git repository for our app. In the terminal, change the working directory to the project’s root directory (if not already at the root).  Recall we can view the working directory using the pwd command, and change the working directory using the cd command.

Now initialize a git repository by issuing the following command in the terminal.

$ git init

We don’t want git to track the files in the node_modules directory since it doesn’t contain our code.  To prevent git from tracking these files we need to first create a new file named .gitignore in the project’s root directory.

Inside .gitignore we add the following line so that the node modules are not copied to the repo.

node_modules/

We can verify that this directory is not tracked by running the following command and noticing that node_modules/ is not listed.

$ git status

We can now add all of the tracked files and directories to the git staging area using the following command.

$ git add .

Next we want to commit the changes to the staged files using the command below.

$ git commit -m "initial commit"

Push Code to GitHub

Now on GitHub, create a new repository by clicking the + in the upper right corner of the webpage. Name the repository and leave all the defaults.

After you’ve created a repository, you should see a box on the webpage that reads Quick setup — if you’ve done this kind of thing before. In that box press, press the SSH button. This changes the commands need to push code using SSH key authentication.

Next, scroll down on the webpage to see some commands listed under …or push an existing repository from the command line. These are the commands we’ll be issuing to push our code from our laptops to GitHub.

Open the terminal in VSC and change the working directory to your app’s root directory. Then issue the following commands to push your code to GitHub, replacing XXXX with your GitHub username and replacing YYYY with the GitHub repository name that you used when you created the repository on GitHub.

$ git remote add origin git@github.com:XXXX/YYYY.git
$ git branch -M main
$ git push -u origin main

If you refresh your GitHub page, you should see your app’s code.

Deploy the App to Heroku

Next, we need to initialize an app on Heroku. This can be done using the heroku create command followed by a name of our application. The name of the application will be used as part of the URL to access the application on heroku.com so it has to be a unique app name that Heroku has not already created.

In VSC, change the working directory to the root directory of your app.  Then issue the following command, replacing unique-app-name with a name that you are sure Heroku has not seen before.  For example, you might use your GitHub user name followed by the name of your VSC project.

$ heroku create unique-app-name

If successful, you will see two links. The first is a link to the live URL that our app will run at. If you navigate to the link in a browser you’ll see a banner stating “Heroku | Welcome to your new app!”. Bookmark the link.  The second is a git repository hosted on heroku.com.

When we initialized the Heroku app above using the Heroku CLI, it created a local git remote named heroku pointing to the git repository on the Heroku server. To see the remote, we can run the following command.

$ git remote

Now to push our code to the Heroku server we run the following command.

$ git push heroku main

After the code is pushed to Heroku we see from the terminal messages that Heroku installed our app and started the application. If we navigate to the link provided in the terminal, we can witness our app is truly running on the Heroku server.

My app is running at https://n0code-hello-world.herokuapp.com.

© 2022 – 2024, Eric McGregor. All rights reserved. Unauthorized use, distribution and/or duplication of this material without express and written permission from the author is strictly prohibited.