Koa-pug

5.1.1 verified Sat Apr 25 auth: no javascript maintenance

Koa-pug is a Pug (formerly Jade) template engine middleware for Koa (v1 and v2) JavaScript web frameworks. Current stable version is 5.1.1, released in 2019, with infrequent updates (last commit 2019). It integrates Pug templates into Koa by binding ctx.render() and supports custom view paths, global helpers via helperPath, and standalone rendering. Key differentiators: seamless Koa integration, helper auto-loading from directories, and Pug@3 support. Alternatives like @ladjs/koa-pug-view are more actively maintained.

Common errors

error TypeError: render is not a function ↓

cause Missing `app` option or `pug.use(app)` not called; ctx.render not bound.

fix

new Pug({ app: app }) or pug.use(app);

error Error: Cannot find module 'pug' ↓

cause Pug package is not installed as a dependency.

fix

npm install pug --save

error Error: Could not find template 'index' ↓

cause Template file not found in viewPath or incorrect path.

fix

Ensure viewPath is correct (defaults to process.cwd()) and template exists.

Warnings

deprecated The package is in maintenance mode; no active development since 2019. ↓

fix Consider using @ladjs/koa-pug-view for active support.

breaking Version 5.x drops support for Node <10 and requires Pug@3. ↓

fix Upgrade Node.js to >=10 and install Pug@3.

gotcha The `app` option must be passed to constructor to bind ctx.render(); otherwise, you must call pug.use(app) after instantiation. ↓

fix Pass { app: app } in options or call pug.use(app).

gotcha When using helperPath, the module filename is converted to camelCase for the helper name. For example, 'format-date.js' becomes 'formatDate'. ↓

fix Use PascalCase or camelCase in filenames to avoid naming conflicts.

Install

npm install koa-pug

yarn add koa-pug

pnpm add koa-pug

Imports

default
wrong
```
import Pug from 'koa-pug'
```
correct
```
const Pug = require('koa-pug')
```
CommonJS only; package does not provide ESM exports. Use require().
default
wrong
```
import { Pug } from 'koa-pug'
```
correct
```
import Pug from 'koa-pug'
```
Default export only; no named exports. Works with ESM loader but required CJS module.
default
wrong
```
const { Pug } = await import('koa-pug')
```
correct
```
const Pug = await import('koa-pug')
```
Dynamic import returns default export as module.default; destructure not needed.

Quickstart

Sets up a Koa server with Pug template rendering using koa-pug middleware.

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

const app = new Koa();
const pug = new Pug({
  viewPath: path.resolve(__dirname, './views'),
  locals: { title: 'Hello' },
  app: app
});

app.use(async ctx => {
  await ctx.render('index', { message: 'World' });
});

app.listen(3000);