tessl/npm-pug

A clean, whitespace-sensitive template language for writing HTML

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Pug

Name: tessl/npm-pug
Author: tessl

Pug is a high-performance template engine for Node.js and browsers that transforms clean, whitespace-sensitive syntax into HTML. It provides a concise and intuitive way to write HTML templates using indentation-based structure, element classes and IDs via CSS selector syntax, JavaScript expressions for dynamic content, conditionals and loops for logic, mixins for reusable components, and includes/extends for template composition.

Package Information

Package Name: pug
Package Type: npm
Language: JavaScript
Installation: npm install pug

Core Imports

const pug = require("pug");

For ES modules:

import pug from "pug";

Basic Usage

const pug = require("pug");

// Compile a template from string
const template = pug.compile('p Hello #{name}!');
const html = template({ name: 'World' });
// Result: <p>Hello World!</p>

// Render directly from string
const html2 = pug.render('h1 Welcome to #{site}', { site: 'Pug' });
// Result: <h1>Welcome to Pug</h1>

// Render from file
const html3 = pug.renderFile('template.pug', { user: 'Alice' });

Architecture

Pug is built around several key components:

Compilation API: Functions to compile templates into reusable functions (compile, compileFile)
Rendering API: Direct template-to-HTML conversion (render, renderFile)
Client-Side Compilation: Generate JavaScript code for browser use (compileClient, compileFileClient)
Template Caching: Built-in caching system for improved performance
Plugin System: Extensible architecture supporting custom processing stages
Express Integration: Native support for Express.js view engine

Capabilities

Template Compilation

Core compilation functionality for transforming Pug templates into executable JavaScript functions. Essential for production applications requiring maximum performance.

/**
 * Compile a Pug template string into a function
 * @param str - Pug template source code
 * @param options - Compilation options
 * @returns Template function that accepts locals and returns HTML string
 */
function compile(str, options);

/**
 * Compile a Pug template file into a function
 * @param path - Path to Pug template file
 * @param options - Compilation options
 * @returns Template function with caching support
 */
function compileFile(path, options);

Template Compilation

Template Rendering

Direct template-to-HTML conversion for simple use cases and development environments. Combines compilation and execution in a single step.

/**
 * Render a Pug template string directly to HTML
 * @param str - Pug template source code
 * @param options - Rendering options including locals
 * @param fn - Optional callback for async operation
 * @returns HTML string (sync) or calls callback (async)
 */
function render(str, options, fn);

/**
 * Render a Pug template file directly to HTML
 * @param path - Path to Pug template file
 * @param options - Rendering options including locals
 * @param fn - Optional callback for async operation
 * @returns HTML string (sync) or calls callback (async)
 */
function renderFile(path, options, fn);

Template Rendering

Client-Side Compilation

Browser-compatible template compilation for client-side rendering. Generates standalone JavaScript code that can run without Node.js dependencies.

/**
 * Compile template to JavaScript source for browser use
 * @param str - Pug template source code
 * @param options - Client compilation options
 * @returns JavaScript source code string
 */
function compileClient(str, options);

/**
 * Compile template file to client-side JavaScript
 * @param path - Path to Pug template file
 * @param options - Client compilation options
 * @returns JavaScript source code string with caching
 */
function compileFileClient(path, options);

/**
 * Compile template with dependency tracking
 * @param str - Pug template source code
 * @param options - Compilation options
 * @returns Object with body (JavaScript code) and dependencies array
 */
function compileClientWithDependenciesTracked(str, options);

Client-Side Compilation

Configuration and Caching

Template caching, global filters, and runtime configuration for optimizing performance and extending functionality.

/**
 * Template function cache for compiled templates
 */
const cache;

/**
 * Global custom filters registry
 */
const filters;

/**
 * Pug runtime helpers for template execution
 */
const runtime;

/**
 * Library identification name
 */
const name;

Configuration and Caching

Express.js Integration

Native Express.js view engine support for seamless web application integration.

/**
 * Express.js view engine interface
 * @param path - Template file path
 * @param options - View options from Express
 * @param fn - Express callback function
 */
function __express(path, options, fn);

Express Integration

Node.js require() Registration

Direct .pug file support through Node.js require() system for seamless template loading in applications.

/**
 * Register .pug extension with Node.js require() system
 */
require('pug/register');

Configuration and Caching

Common Options

Most functions accept an options object with these common properties:

interface PugOptions {
  /** Used for error reporting and resolving includes/extends */
  filename?: string;
  /** Include debugging information (default: true in development) */
  compileDebug?: boolean;
  /** Add pretty-indentation to output (default: false) */
  pretty?: boolean;
  /** Base directory for resolving includes and extends */
  basedir?: string;
  /** Set default doctype if not specified in template */
  doctype?: string;
  /** Custom filters for template processing */
  filters?: { [name: string]: Function };
  /** Options passed to filters */
  filterOptions?: any;
  /** Aliases for filter names */
  filterAliases?: { [alias: string]: string };
  /** Variables to make available globally in templates */
  globals?: string[];
  /** Use self namespace for locals (default: false) */
  self?: boolean;
  /** Enable template caching (requires filename) */
  cache?: boolean;
  /** Inline runtime functions in generated code */
  inlineRuntimeFunctions?: boolean;
  /** Array of compilation plugins */
  plugins?: PugPlugin[];
  /** Include source maps in debug builds */
  includeSources?: boolean;
  /** Name for the generated template function */
  templateName?: string;
  /** Debug compilation process */
  debug?: boolean;
}

Types

/**
 * Compiled template function
 */
type TemplateFunction = (locals?: any) => string;

/**
 * Plugin interface for extending Pug compilation
 */
interface PugPlugin {
  /** Hook into lexical analysis stage */
  lex?: Function;
  /** Hook into parsing stage */
  parse?: Function;
  /** Custom file resolution */
  resolve?: Function;
  /** Custom file reading */
  read?: Function;
  /** Custom code generation */
  generateCode?: Function;
  /** Pre-processing hooks */
  preLex?: Function;
  postLex?: Function;
  preParse?: Function;
  postParse?: Function;
  preLoad?: Function;
  postLoad?: Function;
  preFilters?: Function;
  postFilters?: Function;
  preLink?: Function;
  postLink?: Function;
  preCodeGen?: Function;
  postCodeGen?: Function;
}

/**
 * Compilation result with dependency tracking
 */
interface CompilationResult {
  /** Generated JavaScript code */
  body: string;
  /** Array of file dependencies */
  dependencies: string[];
}