# koa-views

> Template rendering middleware for koa

Latest version **8.1.0** (published 2023-06-09) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

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

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 8.1.0 |
| Published | 2023-06-09 |
| First published | 2014-02-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 25.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 706 |
| Author | queckezz |
| Maintainers | niftylettuce, queckezz, int64ago, titanism |
| Keywords | koa, render, views, app-wide, templating, templates |

## Links

- npm: https://www.npmjs.com/package/koa-views
- Repository: https://github.com/queckezz/koa-views
- Homepage: https://github.com/queckezz/koa-views#readme
- Issues: https://github.com/queckezz/koa-views/issues
- npm.io page: https://npm.io/package/koa-views

## Dependencies (7)

- [mz](https://npm.io/package/mz.md) ^2.7.0
- [debug](https://npm.io/package/debug.md) ^4.3.4
- [pretty](https://npm.io/package/pretty.md) ^2.0.0
- [koa-send](https://npm.io/package/koa-send.md) ^5.0.1
- [get-paths](https://npm.io/package/get-paths.md) 0.0.7
- [resolve-path](https://npm.io/package/resolve-path.md) ^1.4.0
- [@ladjs/consolidate](https://npm.io/package/@ladjs/consolidate.md) ^1.0.1

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 8.1.0 (latest) — 2023-06-09
- 5.2.1 (next) — 2017-02-24
- 8.0.0 — 2021-11-24
- 7.0.2 — 2021-10-26
- 7.0.1 — 2021-03-16
- 7.0.0 — 2020-12-03
- 6.3.1 — 2020-09-21
- 6.3.0 — 2020-06-09
- 6.2.3 — 2020-05-25
- 6.2.2 — 2020-05-11
- 6.2.1 — 2019-09-06
- 6.2.0 — 2019-03-29
- 6.1.5 — 2018-12-17
- 6.1.4 — 2018-02-27
- 6.1.3 — 2017-12-03
- … 28 more at https://npm.io/package/koa-views/versions

## README

# koa-views

![koa-views](https://img.shields.io/github/workflow/status/queckezz/koa-views/koa-views?logo=github&style=flat-square)
[![NPM version][npm-image]][npm-url]
[![NPM downloads][npm-downloads-image]][npm-url]
[![Dependency Status][david-image]][david-url]
[![License][license-image]][license-url]

Template rendering middleware for `koa@2`.

## Installation

```sh
npm install koa-views
```

## Templating engines

`koa-views` is using [@ladjs/consolidate](https://github.com/ladjs/consolidate) under the hood.

[List of supported engines](https://github.com/ladjs/consolidate#engines)

**NOTE**: you must still install the engines you wish to use, add them to your package.json dependencies.

## Example

```js
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](./test/index.js).

## Simple middleware

If you need to simply render pages with locals, you can install `koa-views-render`:

```sh
npm install koa-views-render
```

Then simply use it on your routes and its arguments will be passed to `ctx.render`.

```js
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 use `ctx.body` to receive the rendered template string. Defaults to `true`.

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

```js
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.
```js
app.use(async function (ctx) {
  await ctx.render('user.pug')
})
```

vs.

```js
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.
```js
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 `@ladjs/consolidate` as default engine source

If you’re not happy with `@ladjs/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`.

```js
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 add `partials` and `helpers` etc.

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

```bash
$ DEBUG=koa-views
```

## License

[MIT](./license)

[npm-image]: https://img.shields.io/npm/v/koa-views.svg?style=flat-square
[npm-downloads-image]: https://img.shields.io/npm/dm/koa-views.svg?style=flat-square
[npm-url]: https://npmjs.org/package/koa-views
[david-image]: http://img.shields.io/david/queckezz/koa-views.svg?style=flat-square
[david-url]: https://david-dm.org/queckezz/koa-views
[license-image]: http://img.shields.io/npm/l/koa-views.svg?style=flat-square
[license-url]: ./license

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