Skip to content

chrisyip/koa-pug

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Koa-pug

Node version NPM version Dependency Status Travis CI

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