koa-nunjucks-render

npm install koa-nunjucks-render

A simple koa middleware for rendering nunjucks templates.

This library made some notable improvements over the koa-views at last back when it was first written. I haven't substantiated these claims in some time, but these are what inspired this library:

This library:

• Is faster.
• Doesn't overwrite rendering context variables (e.g. 'engine', 'cache').
• Directly uses nunjucks instead of trying to work with a generalization layer. For example, koa-views would cache the top-level file itself that was rendered via render(template). But then nunjucks would cache nested templates. This lead to weird behaviors like only to the top-level template refreshing during development.

Configuration

const nunjucksRender = require('koa-nunjucks-render')

app.use(nunjucksRender('views', {
  ext: '.html',
  noCache: process.env.NODE_ENV !== 'production',
  throwOnUndefined: true,
  filters: {
    json: value => JSON.stringify(value, null, 2)
  },
  globals: {
    // Can be accessed in every template, {{ myGlobalVariable }}
    myGlobalVariable: 42
  },
  extensions: {
    myExtension: new MyExtension()
}))

The configuration object is passed directly to nunjucks.

Though this library adds some optional convenience keys:

• ext: specify the suffix of your template files such that ctx.render('foo') will look for 'foo' + ext.
• filters: mapping of filter names to filter functions. e.g. {{ user | json }}
• globals: mapping of global identifiers that will be available in your templates.
• extensions: mapping of nunjucks extensions.

Usage

Once you configure and .use() the middleware, it adds a ctx.render(template, locals) method into the koa context object for use in your routes.

router.get('/users/:id', async (ctx) => {
  const user = await db.getUser(ctx.params.id)
  ctx.assert(user, 404)
  await ctx.render('show_user.html', {
    ctx,
    user,
    title: `${user.uname}'s Profile`,
  })
})

Pro tip: It's often useful to pass the koa ctx object into your templates. For example, you may want to inspect ctx.path to know which tab to highlight in a submenu.