Awesome
koa-views
Template rendering middleware for koa@2
.
Installation
npm install koa-views
Templating engines
koa-views
is using 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 path -
opts
(optional) -
opts.autoRender
: Whether to usectx.body
to 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 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
.
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 addpartials
andhelpers
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