or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-gulp-useref

Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets.

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

To install, run

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

index.mddocs/

gulp-useref

gulp-useref is a Gulp plugin that parses build blocks in HTML files to replace references to non-optimized scripts or stylesheets with concatenated and optimized versions. It processes HTML files containing special build block comments and automatically handles asset concatenation and HTML updating.

Package Information

  • Package Name: gulp-useref
  • Package Type: npm
  • Language: JavaScript
  • Installation: 
    npm install --save-dev gulp-useref

Core Imports

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

Basic Usage

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

gulp.task('default', function () {
    return gulp.src('app/*.html')
        .pipe(useref())
        .pipe(gulp.dest('dist'));
});

HTML Build Block Syntax

gulp-useref processes HTML comments in this format:

<!-- build:<type>(alternate search path) <path> <parameters> -->
<!-- endbuild -->

Example:

<html>
<head>
    <!-- build:css css/combined.css -->
    <link href="css/one.css" rel="stylesheet">
    <link href="css/two.css" rel="stylesheet">
    <!-- endbuild -->
</head>
<body>
    <!-- build:js scripts/combined.js -->
    <script type="text/javascript" src="scripts/one.js"></script>
    <script type="text/javascript" src="scripts/two.js"></script>
    <!-- endbuild -->
</body>
</html>

Results in:

<html>
<head>
    <link rel="stylesheet" href="css/combined.css"/>
</head>
<body>
    <script src="scripts/combined.js"></script>
</body>
</html>

Capabilities

Main Plugin Function

Creates a Gulp transform stream that processes HTML files with build blocks.

/**
 * Creates a Gulp transform stream for processing HTML files with build blocks
 * @param {Object} options - Configuration options
 * @param {...Function} transformStreams - Additional transform streams for asset processing
 * @returns {Transform} Gulp transform stream
 */
function useref(options, ...transformStreams);

Usage Examples:

// Basic usage
gulp.src('*.html')
    .pipe(useref())
    .pipe(gulp.dest('dist'));

// With options
gulp.src('*.html')
    .pipe(useref({ 
        searchPath: '.tmp',
        noAssets: false,
        base: 'dist'
    }))
    .pipe(gulp.dest('dist'));

// With transform streams
const lazypipe = require('lazypipe');
const sourcemaps = require('gulp-sourcemaps');

gulp.src('*.html')
    .pipe(useref({}, lazypipe().pipe(sourcemaps.init, { loadMaps: true })))
    .pipe(sourcemaps.write('maps'))
    .pipe(gulp.dest('dist'));

// With conditional processing
const gulpif = require('gulp-if');
const uglify = require('gulp-uglify');
const minifyCss = require('gulp-clean-css');

gulp.src('*.html')
    .pipe(useref())
    .pipe(gulpif('*.js', uglify()))
    .pipe(gulpif('*.css', minifyCss()))
    .pipe(gulp.dest('dist'));

Options

searchPath

/**
 * Location to search for asset files, relative to the current working directory
 * @type {string|string[]}
 * @default undefined
 */
searchPath: string | string[]

Example:

// Single path
useref({ searchPath: '.tmp' })

// Multiple paths
useref({ searchPath: ['.tmp', 'app'] })

base

/**
 * Output folder relative to the cwd
 * @type {string}
 * @default process.cwd()
 */
base: string

noAssets

/**
 * Skip assets and only process the HTML files
 * @type {boolean}
 * @default false
 */
noAssets: boolean

noconcat

/**
 * Skip concatenation and add all assets to the stream instead
 * @type {boolean}
 * @default false
 */
noconcat: boolean

newLine

/**
 * String that should separate the concatenated files
 * @type {string}
 * @default undefined
 */
newLine: string

Example:

// Add semicolon separator for JS files
useref({ newLine: ';' })

additionalStreams

/**
 * Additional streams as sources of assets
 * @type {Stream[]}
 * @default undefined
 */
additionalStreams: Stream[]

Example:

const ts = require('gulp-typescript');

// Create stream of virtual files
const tsStream = gulp.src('src/**/*.ts').pipe(ts());

gulp.src('src/index.html')
    .pipe(useref({ additionalStreams: [tsStream] }))
    .pipe(gulp.dest('dist'));

transformPath

/**
 * Transform function for modifying file paths before search
 * @type {Function}
 * @default undefined
 */
transformPath: (filePath: string) => string

Example:

useref({
    transformPath: function(filePath) {
        return filePath.replace('/rootpath', '')
    }
})

types

/**
 * Asset types to process
 * @type {string[]}
 * @default ['css', 'js']
 */
types: string[]

Build Block Types

CSS Build Block

Concatenates CSS files and updates link tags.

<!-- build:css path/to/combined.css -->
<link href="css/one.css" rel="stylesheet">
<link href="css/two.css" rel="stylesheet">
<!-- endbuild -->

JavaScript Build Block

Concatenates JavaScript files and updates script tags.

<!-- build:js path/to/combined.js -->
<script src="js/one.js"></script>
<script src="js/two.js"></script>
<!-- endbuild -->

Remove Build Block

Removes the entire build block without generating files.

<!-- build:remove -->
<script src="debug-only.js"></script>
<!-- endbuild -->

Error Handling

The plugin handles several error conditions:

  • Streaming files: Throws PluginError with message "Streaming not supported"
  • File processing errors: Emits error events with PluginError instances
  • Missing files: Continues processing, uses original file path patterns if files not found

Stream Behavior

  • Input: Accepts vinyl files in buffer mode
  • Output: Emits processed HTML files and concatenated asset files
  • Async: Handles asynchronous asset processing with proper stream coordination
  • Memory: Uses buffer mode only, no streaming support