pug-layers

Express middleware that extends res.render to serve pug templates at any layer of their extends chain — returning a fragment without outer wrappers.

Install

npm install pug-layers

Usage

const express   = require('express');
const pugLayers = require('pug-layers');

const app = express();
app.set('views', './views');
app.set('view engine', 'pug');

app.use(pugLayers);

// full page — normal Express behaviour, all layers rendered
app.get('/', (req, res) => res.render('page', locals));

// layer 0 — innermost block only, no nav, no layout
app.get('/fragment', (req, res) => res.render('page:0', locals));

// layer 1 — page content only, no nav
app.get('/partial',  (req, res) => res.render('page:1', locals));

// layer 2 — nav + page content, no layout shell
app.get('/with-nav', (req, res) => res.render('page:2', locals));

How layers map to your template chain

Given a three-level inheritance chain:

layout.pug          ← outermost — full HTML shell
  └─ nav.pug        ← layer 2 — nav + content
       └─ page.pug  ← layer 1 — page content
            └─ ...  ← layer 0 — innermost block only

Layer 0 is always the innermost block — the raw fragment with no wrappers. Each increment adds one outer layer. No layer suffix renders the full page as normal.

How it works

res.render('page:N', locals) compiles page.pug with a preCodeGen plugin that intercepts the fully-linked AST — after the entire extends chain has been resolved — and hoists the NamedBlock at depth N to the root, stripping all outer layers. Compiled functions are stored in pug.cache under filename:layer keys and reused on subsequent requests.

Debug

Uses the debug package under the express:pug-layers namespace:

DEBUG=express:pug-layers node app.js
DEBUG=express:*          node app.js

Template structure

Each level must declare a single named block as its contribution:

//- layout.pug
block main

//- nav.pug
extends layout
block main
  nav ...
  main
    block main_content

//- page.pug
extends nav
block main_content
  .page
    block body_content