# koa-pug

> A Pug middleware for Koa

Latest version **5.1.1** (published 2024-02-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-pug
pnpm add koa-pug
yarn add koa-pug
bun add koa-pug
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.1.1 |
| Published | 2024-02-05 |
| First published | 2016-04-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 4 |
| Unpacked size | 16.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | chrisyipw |

## Links

- npm: https://www.npmjs.com/package/koa-pug
- npm.io page: https://npm.io/package/koa-pug

## Dependencies (4)

- [pug](https://npm.io/package/pug.md) ^3.0.2
- [extend](https://npm.io/package/extend.md) ^3.0.2
- [camelcase](https://npm.io/package/camelcase.md) ^6.3.0
- [is-plain-obj](https://npm.io/package/is-plain-obj.md) ^3.0.0

## Recent versions

- 5.1.1 (latest) — 2024-02-05
- 5.1.0 — 2022-12-16
- 5.0.0 — 2021-03-22
- 4.0.4 — 2020-05-28
- 4.0.3 — 2019-12-17
- 4.0.2 — 2019-08-19
- 4.0.1 — 2019-08-19
- 4.0.0 — 2019-08-19
- 3.0.0-2 — 2017-02-09
- 3.0.0-1 — 2016-10-09
- 3.0.0-0 — 2016-04-25

## README

# Koa-pug

[![Node version][node-image]][npm-url] [![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Travis CI][travis-image]][travis-url]

A [Pug](https://github.com/pugjs) middleware for [Koa](http://koajs.com/).

Support Pug@3.

# How to use

```bash
npm install koa-pug --save
```

```js
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`:

```js
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:

```js
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](https://pugjs.org/api/reference.html#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:

```js
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

```js
// 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:

```js
// 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:

```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](https://github.com/chrisyip/koa-pug/graphs/contributors)

[node-image]: https://img.shields.io/node/v/koa-pug.svg?style=flat-square
[npm-url]: https://npmjs.org/package/koa-pug
[npm-image]: https://img.shields.io/npm/v/koa-pug.svg?style=flat-square
[daviddm-url]: https://david-dm.org/chrisyip/koa-pug
[daviddm-image]: https://img.shields.io/david/chrisyip/koa-pug.svg?style=flat-square
[travis-url]: https://travis-ci.org/chrisyip/koa-pug
[travis-image]: https://img.shields.io/travis/chrisyip/koa-pug.svg?style=flat-square

---
_Source: https://npm.io/package/koa-pug · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._