Pug Block Inheritance: Architecture & Best Practices

Problem Statement

Server‑side rendered applications often need a reusable page skeleton. Pug’s extends and block syntax provide a lightweight inheritance system, but without a clear design it can lead to fragile templates, runtime errors, and security issues.

Architectural Requirements

• Define a single source of truth for layout structure.
• Allow child templates to override only the parts that differ.
• Guarantee that missing or misspelled blocks do not silently fail.
• Maintain strict boundaries between static template files and dynamic data.
• Provide fast rendering with optional caching for production.

Minimal Design Pattern

The smallest, most maintainable pattern uses two files:

// layout.pug
doctype html
html
  head
    block head
      title Default Title
  body
    block header
      h1 Default Header
    block content
      p Default Content
    block footer
      p Default Footer

// page.pug
extends layout.pug

block head
  title Custom Page

block header
  h1 Custom Header

block content
  p This page has unique content.

block footer
  p Custom Footer Text

Only the page.pug file changes for each page; the layout remains untouched.

Trust & Data Boundaries

• Templates should be static files on disk. If they are sourced from a CMS or user uploads, never compile them with - or do tags that execute JavaScript.
• Use Pug’s interpolation syntax #{} for all dynamic data to escape HTML automatically.
• When compiling at runtime, enable {cache:true} to avoid re‑parsing the same template repeatedly.

Operational Checks

1. File Resolution: Verify that every extends path points to an existing file. A missing file throws a ENOENT error at compile time.
2. Block Naming: Ensure child blocks match names declared in the parent. If a block is undefined, Pug falls back to the parent’s default content, which may hide missing overrides.
3. Default Content: Provide meaningful defaults in layout.pug so that a missing override still produces a valid page.
4. Cache Management: In production, compile once per deployment or use pug.compileFile with {cache:true} to reduce CPU usage.

Failure Modes

• Misspelled Block Names: The engine silently uses the parent block, leading to confusing output. Enable pug.compileFile('page.pug', { pretty:true }) during development to surface missing overrides.
• Circular Extends: A template that extends itself, directly or indirectly, causes a stack overflow. Detect cycles by maintaining a visited set during compilation.
• Deleted Layout: If layout.pug is removed, all dependent pages fail with a compile error. Version control and CI checks can catch this.

When to Re‑Design

• Moving to a client‑side framework (React, Vue, Svelte) – then Pug templates are replaced by components.
• Introducing dynamic data filtering (Pug filters) that require runtime compilation – consider pre‑compiling templates or using a dedicated templating engine.
• Scaling to thousands of pages – add a naming convention and automated linting to enforce block consistency.

Concrete Example & Verification

Assume a Node.js project with Pug 3.0 installed. Create the two files as shown above in a views directory.

# Terminal: Compile to static HTML
pug views/page.pug --out dist
# Expected: dist/page.html contains the overridden header, content, and footer.

In a Node script, compile and render with data:

const pug = require('pug');
const render = pug.compileFile('views/page.pug', { cache:true });
const html = render({ title:'Dynamic Title' });
console.log(html.includes('Dynamic Title')); // true

To test failure handling, rename content to cntent in page.pug and run the compiler. Pug will emit a clear error: Block 'cntent' not found in layout.

Risk Checklist

• Ensure no - or do tags in templates that originate from untrusted sources.
• Verify that layout.pug is never deleted in a production branch.
• Confirm that caching is enabled in production builds.

Verification Steps

1. Run pug --version to confirm compatibility (works from 2.x onward).
2. Check that the generated HTML contains the expected block content.
3. Run npm test with a linting rule that flags undefined blocks.