Hello and welcome to this tutorial on how to use Koa.js for building dynamic web sites and services. The hope with this is that you can come away with the knowledge and confidence to begin working with Koa to accomplish whatever tasks you may need.

For those less familiar, you may be wondering what exactly is Koa? It's a minimalist web framework for Node.js. It was built by the same people who created Express, and it runs on many of the same principles. However, unlike Express, Koa is made to run on bleeding edge Javascript. More specifically, Koa relies on async/await functions as its core for building out middleware. In many ways, it looks and behaves like Express or Sinatra. You generate base level app object, then begin plugging in the middleware you need before assigning it to a specific port. This minimalistic nature is what makes Koa usable for numerous use cases, from REST APIs to dynamic web sites and many other things in between.

So your next question may be, what exactly are we building? In our case we will keep things simple. We will be building a web site that allows people to search for guitar amps based on their music genre of choice. In doing so, this will allow you to get exposure to a few key ways for how to get things done in Koa. Specifically...

  1. Render server-side views
  2. CSS framework integration (in this case, Foundation)
  3. Database interaction - in this case MongoDb/Mongoose
  4. HTML/CSS Preprocessing with Pug and Stylus
  5. Serving static assets

Getting a handle on how to handle these things will be helpful as we have to remember, Koa is minimalist by design. There is very little that is handed to you by default, but don't worry. That is where this tutorial kicks in to help you along.

Getting Started

First we need to get a handle on the things that we need in order to make this project work. Make sure you have the following items installed or at least have access to them.

  1. Node.js 8.3.0 or higher
  2. Yarn (optional but highly recommended)
  3. MongoDB or a Mongo hosting service such as Mlab.
  4. nodemon (again, option but highly recommended)

So now, let's open our terminal and get started.

cd /path/to/chosen/dir
mkdir ampbuddy
cd ampbuddy
yarn init

Now let's just fill in the default responses for yarn...

git init
touch package.json

Now we need to write out our package.json.

  "name": "KoaIntro",
  "version": "1.0.0",
  "main": "app.js",
  "license": "MIT",
  "scripts": {
    "start": "nodemon app.js"
  "dependencies": {
    "bluebird": "^3.5.0",
    "foundation-sites": "^6.4.3",
    "jquery": "^3.2.1",
    "koa": "^2.3.0",
    "koa-convert": "^1.2.0",
    "koa-simple-router": "^0.2.0",
    "koa-static": "^4.0.1",
    "koa-stylus": "^0.1.0",
    "koa-views": "^6.0.2",
    "mongoose": "^4.11.11",
    "pug": "^2.0.0-rc.4",
    "what-input": "^5.0.1"

Now let's go back to the terminal...

yarn install
mkdir assets views
cd assets
mkdir img js style
mkdir style/foundation
cd ..
mkdir views/includes

Good, now we have installed our modules and we have directories to locate our static assets and views. We'll be returning to these later but for now, let's keep moving along. We need to download some images and a couple of helpful files. So just visit this link to download the zip file that will contain what we need.

Now let's open our zip file, and take a look at what we have inside...


First, let's open the images folder then copy/paste these over to our /assets/img folder in the project directory. Now we need to go back and copy/paste amps.json and preload.js over to our project's root directory. amps.json is just a load of pre-written data that our application will depend on. preload.js is a simple script which will transfer the JSON data in amps.json and save it to a Mongo database of our choosing.

However, we will come back to this in a minute. First we need handle some more housekeeping. Namely, we need to set up Foundation so it can be usable for our application. To do this, let's locate foundation-sites/ inside node_modules/. Now we need to move foundation.css to /assets/style/foundation/foundation.css. Next, we need to move the Foundation javascript files. To do this, let's locate foundation.js and move it to /assets/js/foundation.js. Now we just need to do the same thing with jQuery and What-input.

Good, now let's turn back to our terminal and cd to the app's root directory then enter touch config.js. Now let's write out some code.

module.exports = {
  mongoUrl: 'your-mongo-here'

Easy, now we just need to fill in the URL for our Mongo instance.

Now that we have done that, let's go back to the terminal and run that preload.js script from earlier.

node preload.js

Excellent, now that our data has been saved, we have finished all the groundwork we need to begin writing our app.


This concludes Day 1 for our journey into Koa.js. We learned a little about what Koa.js is, then we laid out the groundwork for writing our application. Tomorrow, we will begin writing our core server portion of our application.

Helpful Links