How To Build a "Hello World" Application with Koa

PostedDecember 12, 2019 2.2k views Node.js

While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

Introduction

Express is one of the most popular Node.js frameworks out there. Koa is a new web framework created by the team behind Express. It aims to be a modern and more minimalist version of Express. Some of its characteristics are its support and reliance on new JavaScript features such as generators and async/await. Koa also does not ship with any middleware though it can be extended using custom and existing plugins.

By following this article, you will learn more about the Koa framework and build an app to get familiar with its functionality and philosophy.

Prerequisites

To follow along with this tutorial, you would need the following installed:

You also need to have a working knowledge of JavaScript and ES6 syntax.

Setup and Configuration

To begin, create a new directory for your project. This can be done by copying and running the command below in your terminal:

  • mkdir koala

Note: You can give your project any name, but in this article we’ll be using koala as the project name and directory.

At this point, you have created your project directory koala. Next, initialise your node project from inside the directory. You can do so by running the commands below:

  • cd koala
  • npm init koala

After running the npm init command, follow the prompts and fill in the details of your project. At the end of this, you will have a package.json file with the information you entered while prompted. Note that you can run npm init -y to create a package.json file with default values.

Next, run this command to install Koa:

  • npm install koa --save

Depending on the version of Node you have running you may not need to add the --save flag. This flag tells older versions of Node to add the installed library (in this case Koa) to the dependencies list in your package.json file. On newer Node versions, you can just run npm i koa to install Koa.

Creating a Koa Server

During the initialization of your project, you were prompted to enter the entry point of your application. In this article, you will use index.js which was the default value as your entry point.

First, create the index.js file. This can be done in several ways. For MacOS and Linux users, this can be done by running the below command in your terminal:

  • touch index.js

Using your code/text editor of choice, open your project and copy the below snippet into the index.js file:

 // index.js

'use strict';

const koa = require('koa')
const app = new koa()

app.use(function *(){
  this.body = "Hello World !!!";
});

app.listen(1234)

In the snippet above, you created a koa application that runs on port 1234. You can run the application using the command:

  • node index.js

And visit the application on http://localhost:1234.

Building Out Your App

As mentioned earlier, Koa.js does not ship with any contained middleware and unlike its predecessor, Express, it does not handle routing by default.

In order to implement routes in your Koa app, you will install a middleware library for routing in Koa, Koa Router. Install it by running:

  • npm install koa-router --save

To make use of the router in your application, amend your index.js file:

// index.js

'use strict';
const koa = require('koa')
const koaRouter = require('koa-router')

const app = new koa()
const router = new koaRouter()

router.get('koala', '/', (ctx) => {
  ctx.body = "Welcome! To the Koala Book of Everything!"
})

app.use(router.routes())
  .use(router.allowedMethods())

app.listen(1234, () => console.log('running on port 1234'))

Above, you have defined a route on the base url of your application (http://localhost:1234) and registered this route to your Koa application.

For more information on route definition in Koa.js applications, visit the Koa Router library documentation here.

As already established, Koa comes as a minimalistic framework, therefore, to implement view rendering with a template engine you will have to install a middleware library. There are several libraries to choose from but in this article you will use koa-ejs.

To do so, first install the library using:

  • npm install koa-ejs --save

Next, amend your index.js file to register your templating with the snippet below:

// index.js

'use strict';
const koa = require('koa')
const path = require('path')
const render = require('koa-ejs')
const koaRouter = require('koa-router')

const app = new koa()
const router = new koaRouter()

render(app, {
  root: path.join(__dirname, 'views'),
  layout: 'layout',
  viewExt: 'html',
  cache: false,
  debug: true
})

router.get('koala', '/', (ctx) => {
  ctx.body = "Welcome! To the Koala Book of Everything!"
})

app.use(router.routes())
  .use(router.allowedMethods())

app.listen(1234, () => console.log('running on port 1234'))

As seen above, in your template registering, you tell your application the root directory of your view files, the extension of the view files and the base view file (which other views extend).

Now that you have registered your template middleware, amend your route definition to render a template file:

// index.js

...

router.get('koala', '/', (ctx) => {
  let koala_attributes = [];
  koala_attributes.push({
    meta_name: 'Color',
    meta_value: 'Black and white'
  })
  koala_attributes.push({
    meta_name: 'Native Country',
    meta_value: 'Australia'
  })
  koala_attributes.push({
    meta_name: 'Animal Classification',
    meta_value: 'Mammal'
  })
  koala_attributes.push({
    meta_name: 'Life Span',
    meta_value: '13 - 18 years'
  })
  koala_attributes.push({
    meta_name: 'Are they bears?',
    meta_value: 'no!'
  })
  return ctx.render('index', {
    attributes: koala_attributes
  })
})

...

Above, your base route renders the index.html file found in the views directory. Your index.html file contains some basic HTML to display your koala attributes. See below:

<!-- views/index.html -->

<h2>Koala - a directory Koala of attributes</h2>
<ul class="list-group">
  <% attributes.forEach( function(attribute) { %>
    <li class="list-group-item">
      <%= attribute.meta_name %> - <%= attribute.meta_value %>
    </li>
  <% }); %>
</ul>

For more options with using the koa-ejs template middleware, view the library documentation here.

Handling Errors and Responses

Koa handles errors by defining an error middleware early in your entrypoint file. The error middleware must be defined early because only errors from middleware defined after the error middleware will be caught. Using your index.js file as an example, adjust it to include:

// index.js

'use strict';
const koa = require('koa')
const render = require('koa-ejs')
const koaRouter = require('koa-router')

const app = new koa()
const router = new koaRouter()

app.use( async (ctx, next) => {
  try {
    await next()
  } catch(err) {
    console.log(err.status)
    ctx.status = err.status || 500;
    ctx.body = err.message;
  }
})

...

The above block catches any error thrown during the execution of your application. We’ll test this by throwing an error in the function body of the route you defined:

// index.js

...

router.get('koala', '/', (ctx) => {
  ctx.throw('Test Error Message', 500)
}) 
...

The Koa response object is usually embedded in its context object. Using route definition, let’s show an example of setting responses:

// index.js

'use strict';
const koa = require('koa')
const koaRouter = require('koa-router')

const app = new koa()
const router = new koaRouter()

app.use( async (ctx, next) => {
  try {
    await next()
  } catch(err) {
    console.log(err.status)
    ctx.status = err.status || 500;
    ctx.body = err.message;
  }
})

router.get('koala', '/', (ctx) => {
  ctx.status = 200
  ctx.body   = "Well this is the response body"
})

Conclusion

In this article, you had a brief introduction to Koa and how to implement some common functionalities in a Koa project. Koa is a minimalist and flexible framework that can be extended to more functionality than this article has shown. Because of its futuristic similarity to Express, some have even described it as Express 5.0 in spirit.

The entire code from this article is available on Github, and the repository contains some additional concepts not treated here, as they are beyond the scope of the introduction.

0 Comments

Creative Commons License