Mastering Modular UI with Pug Inheritance and Mixins

The primary challenge in maintaining large-scale HTML projects is code duplication, where structural elements like headers, footers, and navigation are repeated across multiple files. To solve this, Pug (formerly Jade) uses template inheritance and mixins. This approach allows you to define a master layout once and inject specific content into it, ensuring structural consistency and making global updates instantaneous.

Template Inheritance with Extends and Blocks

Instead of including a header in every file, Pug uses the extends keyword to create a parent-child relationship. The parent template defines placeholders using the block keyword, which child templates then fill with unique content.

In the example below, layout.pug serves as the skeleton for the entire application.

// layout.pug
html
  head
    title My Application
    link(rel="stylesheet" href="/css/style.css")
  body
    header
      h1 Welcome to the Site
    main
      block content
    footer
      p © 2023 Company

The child template, index.pug, extends the layout and overrides only the content block.

// index.pug
extends layout.pug

block content
  h2 Dashboard
  p This is the unique content for the home page.
  button(class="btn-primary" onclick="alert()") Click Me

Reusable Components with Mixins

While inheritance handles page structure, mixins handle repetitive UI components. Think of a mixin as a JavaScript function that returns HTML. This allows you to generate complex elements like cards or buttons with varying data.

The following configuration defines a mixin for a user card that accepts a name, role, and image.

// Define the mixin at the top of the file or in a separate module
mixin userCard(name, role, img)
  div.user-card
    img(src=img, alt=name)
    div.info
      h3= name
      p= role

// Call the mixin with different arguments
+userCard("Alice", "Engineer", "/assets/alice.jpg")
+userCard("Bob", "Designer", "/assets/bob.jpg")

Verification and Compilation

To compile these files into standard HTML, use the Pug CLI. Ensure you have Pug installed globally or via npm. Run the following in your terminal:

# Compile index.pug to index.html
pug index.pug -o .

Check the generated index.html to verify that the main block is correctly nested within the body and that the mixins generated two distinct div elements.

Limitations and Common Pitfalls

• Indentation Sensitivity: Pug relies on whitespace to determine hierarchy. Mixing tabs and spaces within the same file will cause compilation errors. Stick to one (usually 2 spaces) consistently.
• Logic Overload: While Pug supports if and each loops, placing complex business logic inside templates makes them difficult to debug. Process your data in JavaScript before passing it to the template whenever possible.
• Escaping: Pug escapes HTML characters by default to prevent XSS. If you need to render raw HTML (like from a CMS), you must use the exclamation operator (e.g., !{rawContent}). Use this sparingly to avoid security vulnerabilities.