queckezzkoa-views
Template rendering middleware for koa@2.
Installation
npm install koa-views
Templating engines
koa-views is using @ladjs/consolidate under the hood.
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 pathopts(optional)opts.autoRender: Whether to usectx.bodyto receive the rendered template string. Defaults totrue.
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/consolidateas 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 addpartialsandhelpersetc.
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