or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-gulp-pug

Gulp plugin for compiling Pug templates into HTML or JavaScript with support for locals, custom instances, and client-side compilation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gulp-pug@5.0.x

To install, run

npx @tessl/cli install tessl/npm-gulp-pug@5.0.0

index.mddocs/

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:

  1. Via options.locals or options.data: Data passed directly in the plugin configuration
  2. Via file.data: Data attached to individual Vinyl file objects (e.g., using gulp-data)
  3. 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;
}