Koa-pug

A Pug middleware for Koa.

Support Pug@3.

How to use

npm install koa-pug --save

const Koa = require('koa')
const path = require('path')
const Pug = require('koa-pug')

const app = new Koa()
const pug = new Pug({
  viewPath: path.resolve(__dirname, './views'),
  locals: { /* variables and helpers */ },
  basedir: 'path/for/pug/extends',
  helperPath: [
    'path/to/pug/helpers',
    { random: 'path/to/lib/random.js' },
    { _: require('lodash') }
  ],
  app: app // Binding `ctx.render()`, equals to pug.use(app)
})

pug.locals.someKey = 'some value'

app.use(async ctx => {
  await ctx.render('index', locals, true)
})

For koa@1:

const koa = require('koa')
const Pug = require('koa-pug')

const app = koa()
const pug = new Pug({ app: app })

app.use(function * () {
  yield this.render('index', locals, true)
})

Use koa-pug as a standalone Pug renderer:

const pug = new Pug({
  viewPath: path.resolve(__dirname, './views'),
  locals: { /* variables and helpers */ },
  basedir: 'path/for/pug/extends',
  helperPath: [
    'path/to/pug/helpers',
    { random: 'path/to/lib/random.js' },
    { _: require('lodash') }
  ],
  // Can work with / without Koa
  // app: app
})

async function sendEmail(recipients, tplFile, locals) {
  const body = await pug.render(tplFile, locals)
  await send(recipients, body)
}

Options

options are extended from Pug's options, all options will be passed to Pug compiler except the following:

viewPath: string: the location of Pug templates. Default is process.cwd().

locals: { [key: string]: any }: variables and helpers that will be passed to Pug compiler.

helperPath: string | string[] | { [key string]: string }: location(s) of helper(s).

Content-Type

koa-pug will set content-type to text/html for you, you can change it:

await ctx.render('index')
ctx.type = 'text/plain'

Global Helpers

By setting helperPath, koa-pug will load all the modules that under sepecified folxder, and make them available on all templates.

helperPath also could be an array including folders, files path, even moduleName: 'path/to/lib.js mapping object. Also support node module as a helper, just like: '_': require('lodash')

Defining a Helper

// format-date.js, `koa-pug` will convert filename to camel case and use it as module name
module.exports = function (input) {
  return (input.getMonth() + 1) + '/' + input.getDate() + '/' + input.getFullYear()
}

Equals to:

// Becasue of there is a `moduleName`, `koa-pug` will use it as module name instead of filename
module.exports = {
  moduleName: 'formatDate',
  moduleBody (input) {
    return (input.getMonth() + 1) + '/' + input.getDate() + '/' + input.getFullYear()
  }
}

Use help in Pug:

p= formatDate(new Date())

How `koa-pug` resolves Pug template files

Let's say the project views structure like:

views
├── user.pug
├── user
│   └── index.pug
└── file
    └── index.pug

koa-pug will search file in the following order:

<tpl_name>.pug
<tpl_name>/index.pug

When pug.render('user') is called, views/user.pug will be rendered. If you want to render views/user/index.pug, you have to pass it to renderer explicitly: pug.render('user/index).

When pug.render('file') is called, views/file/index.pug will be rendered.

Contributors

Via GitHub

ryota-ka/koa-pug