Pug 3.x Promise returns vs Express.js callback-based res.render integration

Answer

The built‑in pug.__express adapter in Pug 3.x does not await the Promise returned by a compiled template that uses await, async mixins, or async includes. It simply passes the Promise to the callback, which Express expects to receive a string. As a result, rendering such templates with res.render produces unhandled rejections or empty responses.

To use async templates, wrap pug.renderFile (or pug.__express) in your own middleware that checks the return value. If it’s a Promise, await it and then call the callback with the resolved string. This wrapper can be applied per‑route or globally, leaving legacy synchronous templates untouched.

Why the adapter fails

• Compiled templates that contain await return Promise<string>.
• Express’s res.render calls the view engine’s __express callback synchronously and expects a string or an error.
• When the callback receives a Promise, Express treats it as an error‑free string, immediately sending an empty response and leaving the Promise unhandled.

Recommended wrapper pattern

const pug = require('pug');
const original = pug.__express;

function asyncAdapter(filePath, options, callback) {
  try {
    const result = original(filePath, options, callback);
    if (result && typeof result.then === 'function') {
      // The compiled template returned a Promise.
      result
        .then(html => callback(null, html))
        .catch(err => callback(err));
    }
    // If result is a string, the original callback already handled it.
  } catch (err) {
    callback(err);
  }
}

module.exports = asyncAdapter;

Use this adapter in Express:

app.set('view engine', 'pug');
app.set('views', path.join(__dirname, 'views'));
app.engine('pug', asyncAdapter); // replace the default

Gradual migration

1. Keep the default pug.__express for legacy routes that never use await.
2. For new routes that need async mixins or includes, use the wrapper or explicitly call await pug.renderFile(...) in the route handler and then res.send.
3. Test both sync and async routes to confirm no side‑effects.

Handling async mixins

Async mixins force the whole template to be async. If you need to support both sync and async rendering in the same codebase, either:

• Guard the mixin with a runtime check and fall back to a sync version when not needed.
• Create separate view files for sync and async paths and route to the appropriate one.

Verification steps

1. Inspect node_modules/pug/lib/index.js to confirm the adapter does not await the result.
2. Render a template with an async mixin via res.render and observe that the response is empty.
3. Apply the wrapper, re‑render the same template, and verify the HTML appears correctly.
4. Check Express error handling middleware to ensure unhandled Promise rejections are logged.

Missing diagnostic detail

Does your code sometimes call pug.renderFile directly (outside of res.render)? If so, you’ll need to wrap that call as well to avoid unhandled rejections.