gulp-useref

library5.0.0jsnpmunverified

gulp-useref is a Gulp plugin designed to optimize front-end asset loading by processing special "build blocks" within HTML files. It concatenates multiple script or stylesheet references into a single optimized file, subsequently replacing the original tags with a single, updated reference. Currently at version 5.0.0, the package primarily focuses on concatenation and reference management, explicitly stating that it does not handle minification. For minification and other asset transformations, it is intended to be used in conjunction with other Gulp plugins like `gulp-if`, `gulp-uglify`, and `gulp-clean-css`. Its core differentiator lies in streamlining HTML asset references within a Gulp build pipeline, reducing HTTP requests and simplifying asset delivery. The project has not seen recent updates (last published 5 years ago), suggesting it is in maintenance mode rather than active development.

devops

npm install gulp-useref

github ↗package ↗

INSTALL

IMPORT

SIG · GULP-USEREF

gulp-useref

devopsjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useref

✓ import useref from 'gulp-useref';

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

While the documentation primarily shows CommonJS `require`, modern Gulp (v4+) supports ESM, making `import` the preferred method when using ESM in your `gulpfile.mjs` or `package.json` with `"type": "module"`.

useref (CommonJS)

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

This is the primary import method shown in older documentation and for CommonJS-based Gulp setups (e.g., `gulpfile.js` without `"type": "module"`).

This quickstart demonstrates how to parse HTML build blocks, concatenate JavaScript and CSS files, and then minify them using `gulp-if`, `gulp-uglify`, and `gulp-clean-css` before outputting to a `dist` directory.

import gulp from 'gulp'; import useref from 'gulp-useref'; import gulpif from 'gulp-if'; import uglify from 'gulp-uglify'; import cleanCss from 'gulp-clean-css'; gulp.task('html', () => { return gulp.src('app/*.html') .pipe(useref()) .pipe(gulpif('*.js', uglify())) .pipe(gulpif('*.css', cleanCss())) .pipe(gulp.dest('dist')); }); // To run this task, ensure 'app/' contains at least one HTML file // with a build block, e.g., index.html: //  // <link href="css/one.css" rel="stylesheet"> // <link href="css/two.css" rel="stylesheet"> //  //  // <script type="text/javascript" src="scripts/one.js"></script> // <script type="text/javascript" src="scripts/two.js"></script> //

Debug

Known issues

breakingVersion 3.0 introduced significant API changes, simplifying the overall usage. Previous methods like `useref.assets()` are no longer available.

fix

Rewrite Gulp pipelines to directly pipe HTML streams to `useref()` without intermediate `assets()` calls. Refer to the v3 migration notes for examples.

affects: >=3.0.0

gotcha`gulp-useref` only handles concatenation and replacement of references in HTML. It does not perform minification, transpilation, or any other asset optimization itself.

fix

Always combine `gulp-useref` with other Gulp plugins like `gulp-if`, `gulp-uglify`, and `gulp-clean-css` (or `gulp-terser`, `gulp-postcss`, etc.) to achieve full asset optimization.

affects: >=1.0.0

deprecatedThe package's latest version (5.0.0) was published 5 years ago, indicating it is no longer actively maintained. While it still functions, new features or critical bug fixes are unlikely.

fix

Consider evaluating alternative Gulp plugins or modern build tools like Webpack, Rollup, or Vite for projects requiring active development and broader optimization features. If staying with Gulp, ensure thorough testing.

affects: >=5.0.0

Errors

Common errors & fixes

TypeError: useref.assets is not a function

This error typically occurs when migrating from `gulp-useref` v2 to v3 or later, where the `assets()` method was removed from the API.

fix

Remove any calls to `.pipe(useref.assets())` and `.pipe(assets.restore())`. The v3+ API simplifies the process by returning both HTML and asset streams directly from `useref()`.

Error [ERR_REQUIRE_ESM] when using gulp-useref with ESM-only Gulp setup

`gulp-useref` is a CommonJS module, and `require()`ing it directly in a Gulpfile configured for ESM (`gulpfile.mjs` or `"type": "module"` in `package.json`) can lead to this error, especially if your Gulp setup or other plugins are pure ESM.

fix

If running a pure ESM Gulp setup, you might need to use dynamic `import()` (which returns a promise and complicates Gulp's synchronous pipeline) or, more practically, ensure your Gulpfile is CommonJS (`gulpfile.js` without `"type": "module"`) or find a different plugin. Alternatively, `import useref from 'gulp-useref'` might work in some ESM contexts, but compatibility can vary.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

gulprequiredPeer dependency as a Gulp plugin, required for orchestration of build tasks.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jonkemp/gulp-useref ↗

packagehttps://www.npmjs.com/package/gulp-useref ↗