or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Gulp Pug

Gulp Pug is a Gulp plugin for compiling Pug templates into HTML or JavaScript. It integrates seamlessly with Gulp build pipelines to transform .pug files through the streaming interface, supporting template data injection, custom Pug instances, client-side compilation for browser use, and verbose logging options.

Package Information

Package Name: gulp-pug
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install gulp-pug

Core Imports

const pug = require('gulp-pug');

For ES modules:

import pug from 'gulp-pug';

Basic Usage

const { src, dest } = require('gulp');
const pug = require('gulp-pug');

exports.views = () => {
  return src('./src/*.pug')
    .pipe(
      pug({
        // Your options in here.
      })
    )
    .pipe(dest('./dist'));
};

Capabilities

Pug Template Compilation

Creates a Gulp transform stream that compiles Pug template files into HTML or JavaScript.

/**
 * Creates a Gulp transform stream for compiling Pug templates
 * @param options - Configuration options extending Pug's native options
 * @returns Transform stream for processing .pug files
 */
function gulpPug(options?: GulpPug.Options): Transform;

interface GulpPug.Options extends PugOptions {
  /** Locals to compile the Pug with. Merged with file.data if present */
  locals?: any;
  
  /** Same as locals, alternative property name */
  data?: any;
  
  /** Compile Pug to JavaScript code instead of HTML */
  client?: boolean;
  
  /** A custom instance of Pug for gulp-pug to use */
  pug?: any;
  
  /** Legacy alias for pug option (deprecated, use pug instead) */
  jade?: any;
  
  /** Display name of file from stream that is being compiled */
  verbose?: boolean;
}

Usage Examples:

const { src, dest } = require('gulp');
const pug = require('gulp-pug');

// Basic HTML compilation
function compileTemplates() {
  return src('src/templates/*.pug')
    .pipe(pug())
    .pipe(dest('dist/html'));
}

// With template data
function compileWithData() {
  return src('src/templates/*.pug')
    .pipe(pug({
      locals: {
        title: 'My Website',
        description: 'A great website built with Pug'
      }
    }))
    .pipe(dest('dist/html'));
}

// Client-side JavaScript compilation
function compileForClient() {
  return src('src/templates/*.pug')
    .pipe(pug({
      client: true
    }))
    .pipe(dest('dist/js/templates'));
}

// With verbose logging
function compileVerbose() {
  return src('src/templates/*.pug')
    .pipe(pug({
      verbose: true,
      locals: {
        env: 'development'
      }
    }))
    .pipe(dest('dist/html'));
}

// Using custom Pug instance
const customPug = require('pug');
customPug.filters.myFilter = function(text) {
  return text.toUpperCase();
};

function compileWithCustomPug() {
  return src('src/templates/*.pug')
    .pipe(pug({
      pug: customPug
    }))
    .pipe(dest('dist/html'));
}

Template Data Integration

The plugin supports multiple ways to provide template data:

Via options.locals or options.data: Data passed directly in the plugin configuration
Via file.data: Data attached to individual Vinyl file objects (e.g., using gulp-data)
Merged data: File-specific data takes precedence and is merged with options data

const { src, dest } = require('gulp');
const pug = require('gulp-pug');
const data = require('gulp-data');

function compileWithFileData() {
  return src('src/templates/*.pug')
    .pipe(data(function(file) {
      // Data specific to each file
      return {
        filename: file.relative,
        timestamp: new Date()
      };
    }))
    .pipe(pug({
      locals: {
        // Global data for all files
        siteName: 'My Site'
      }
    }))
    .pipe(dest('dist/html'));
}

File Processing Behavior

Input: .pug files via Vinyl file objects
Output: .html files (default) or .js files (when client: true)
Extension handling: Automatically changes file extensions from .pug to target format
Error handling: Provides detailed error messages with filename context using PluginError
Streaming: Fully compatible with Gulp's streaming interface

Error Handling

The plugin wraps compilation errors in Gulp-standard PluginError objects with filename context:

function handleErrors() {
  return src('src/templates/*.pug')
    .pipe(pug())
    .on('error', function(err) {
      console.error('Pug compilation error:', err.message);
      console.error('File:', err.fileName);
      this.emit('end'); // Prevent pipe breaking
    })
    .pipe(dest('dist/html'));
}

Types

interface Transform extends NodeJS.ReadWriteStream {
  // Node.js Transform stream interface
}

interface PugOptions {
  // All standard Pug compilation options from pugjs.org/api/reference.html
  filename?: string;
  basedir?: string;
  doctype?: string;
  pretty?: boolean | string;
  filters?: Record<string, Function>;
  self?: boolean;
  debug?: boolean;
  compileDebug?: boolean;
  globals?: string[];
  cache?: boolean;
  inlineRuntimeFunctions?: boolean;
  name?: string;
}