Template rendering middleware for koa (hbs, swig, pug, anything! )
Clone or download
Latest commit ebc8f27 Dec 17, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Make render available on ctx.response Feb 26, 2018
test Make render available on ctx.response Feb 26, 2018
.eslintrc Add linter & ruleset Mar 1, 2016
.gitattributes force LF even on windows Mar 10, 2015
.gitignore don't compile to ES5, #89 (#90) Mar 1, 2017
.npmignore compile down to es5 Sep 12, 2016
.travis.yml chore: test only on node v8 Dec 20, 2017
history.md update history.md Mar 1, 2017
license licence -> license Nov 30, 2014
package.json Version 6.1.5 Dec 17, 2018
readme.md Add include engines note Dec 13, 2018



Build status NPM version NPM downloads Dependency Status License

Template rendering middleware for koa@2.


npm install koa-views

Templating engines

koa-views is using consolidate under the hood.

List of supported engines

NOTE: you must still install the engines you wish to use, add them to your package.json dependencies.


var views = require('koa-views');

// Must be used before any router is used
app.use(views(__dirname + '/views', {
  map: {
    html: 'underscore'

app.use(async function (ctx) {
  ctx.state = {
    session: this.session,
    title: 'app'

  await ctx.render('user', {
    user: 'John'

For more examples you can take a look at the tests.

Simple middleware

If you need to simply render pages with locals, you can install koa-views-render:

npm install koa-views-render

Then simply use it on your routes and its arguments will be passed to ctx.render.

var render = require('koa-views-render');

// ...

app.use(render('home', { title : 'Home Page' }));


views(root, opts)

  • root: Where your views are located. Must be an absolute path. All rendered views are relative to this path
  • opts (optional)
  • opts.extension: Default extension for your views

Instead of providing the full file extension you can omit it.

app.use(async function (ctx) {
  await ctx.render('user.pug')


app.use(views(__dirname, { extension: 'pug' }))

app.use(async function (ctx) {
  await ctx.render('user')
  • opts.map: Map a file extension to an engine

In this example, each file ending with .html will get rendered using the nunjucks templating engine.

app.use(views(__dirname, { map: {html: 'nunjucks' }}))

// render `user.html` with nunjucks
app.use(async function (ctx) {
  await ctx.render('user.html')
  • opts.engineSource: replace consolidate as default engine source

If you’re not happy with consolidate or want more control over the engines, you can override it with this options. engineSource should be an object that maps an extension to a function that receives a path and options and returns a promise. In this example templates with the foo extension will always return bar.

app.use(views(__dirname, { engineSource: {foo: () => Promise.resolve('bar')}}))

app.use(async function (ctx) {
  await ctx.render('index.foo')
  • opts.options: These options will get passed to the view engine. This is the time to add partials and helpers etc.
const app = new Koa()
  .use(views(__dirname, {
    map: { hbs: 'handlebars' },
    options: {
      helpers: {
        uppercase: (str) => str.toUpperCase()

      partials: {
        subTitle: './my-partial' // requires ./my-partial.hbs
  .use(function (ctx) {
    ctx.state = { title: 'my title', author: 'queckezz' }
    return ctx.render('./my-view.hbs')


Set the DEBUG environment variable to koa-views when starting your server.

$ DEBUG=koa-views