koa-views

Template rendering middleware for koa@2.

Installation

npm install koa-views

Templating engines

koa-views is using @ladjs/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.

Example

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

const render = views(__dirname + '/views', {
  map: {
    html: 'underscore'
  }
})

// Must be used before any router is used
app.use(render)
// OR Expand by app.context
// No order restrictions
// app.context.render = render()

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' }));

API

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.autoRender: Whether to use ctx.body to receive the rendered template string. Defaults to true.

const render = views(__dirname, { autoRender: false, extension: 'pug' });
app.use(render)
// OR
// app.context.render = render()

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

vs.

const render = views(__dirname, { extension: 'pug' })
app.use(render)
// OR
// app.context.render = render()

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

• 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')
})

vs.

const render = views(__dirname, { extension: 'pug' })
app.use(render)
// OR
// app.context.render = render()

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.

const render = views(__dirname, { map: {html: 'nunjucks' }})
app.use(render)
// OR
// app.context.render = render()
// render `user.html` with nunjucks
app.use(async function (ctx) {
  await ctx.render('user.html')
})

• opts.engineSource: replace @ladjs/consolidate as default engine source

If you’re not happy with @ladjs/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.

const render = views(__dirname, { engineSource: {foo: () => Promise.resolve('bar')}})
app.use(render)
// OR
// app.context.render = render()

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
      },
      
      cache: true // cache the template string or not
    }
  }))
  .use(function (ctx) {
    ctx.state = { title: 'my title', author: 'queckezz' }
    return ctx.render('./my-view.hbs')
  })

Debug

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

$ DEBUG=koa-views

License

MIT