pug-render v2.0.0
pug-render
npm install pug-render
A wrapper around Pug with some improvements and a better API.
Improvements
Asynchronous filesystem reads. Pug's
renderFile()
synchronously reads the template source from the filesystem.Because this is suboptimal, this library insteads reads from the filesystem asynchronously. Parallel requests for the same template only trigger a single filesystem read.
Pass in template locals and rendering options separately.
pug.renderFile('hello.pug', { debug: true })
passesdebug
into thehello.pug
template. But thedebug
key is also one of Pug's options, so it also turns debug output on for this render.This means it's possible to accidentally/silently override Pug options with keys that were only intended for the template. This library protects against this by throwing an error if you try to use one of Pug's "reserved" options keys in your template locals.
Additional rendering options. e.g. root template directory, global locals, implicit extensions.
- Absolute includes. Any absolute includes like
include /master.pug
(i.e. starts with "/") will be looked up from the configured root directory.
Usage
Here are the default options.
const makeRender = require('pug')
const templateRoot = require('path').join(__dirname, 'views')
const render = makeRender(templateRoot, {
cache: process.env.NODE_ENV === 'production',
// Use this extension if template path doesn't specify one.
ext: '.pug',
// Expose locals to all templates.
// Template locals are merged into these.
locals: {},
})
// will expect template at './views/homepage.pug'
render('homepage', { title: 'Homepage' })
.then(html => console.log('html:', html))
.catch(console.error)
Koa example
Here's a middleware function that extends the koa context
with a ctx.render()
function which renders a pug
template and updates the response.
const pugRender = require('pug-render')
const middleware = (root, opts) => {
const render = pugRender(root, opts)
return async (ctx, next) => {
ctx.render = async (templatePath, locals) => {
ctx.type = 'html'
ctx.body = await render(templatePath, locals)
}
return next()
}
}
app.use(middleware(require('path').join(__dirname, 'views'), {
locals: {
env: process.env
}
}))
app.get('/', async ctx => {
// Remember to `await` the promise.
await ctx.render('homepage', { title: 'Homepage' })
})
Debug
This library uses debug for debug output under the "pug-render" namespace.
To see this output, launch node with:
DEBUG=pug-render node file.js
It will print out the full path of the template files as it looks them up.