{"id":13277,"library":"gulp-useref","title":"Gulp Useref","description":"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.","status":"maintenance","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jonkemp/gulp-useref","tags":["javascript","gulpplugin","html","scripts","css","optimize","concat"],"install":[{"cmd":"npm install gulp-useref","lang":"bash","label":"npm"},{"cmd":"yarn add gulp-useref","lang":"bash","label":"yarn"},{"cmd":"pnpm add gulp-useref","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as a Gulp plugin, required for orchestration of build tasks.","package":"gulp","optional":false}],"imports":[{"note":"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\"`.","wrong":"const useref = require('gulp-useref');","symbol":"useref","correct":"import useref from 'gulp-useref';"},{"note":"This is the primary import method shown in older documentation and for CommonJS-based Gulp setups (e.g., `gulpfile.js` without `\"type\": \"module\"`).","symbol":"useref (CommonJS)","correct":"const useref = require('gulp-useref');"}],"quickstart":{"code":"import gulp from 'gulp';\nimport useref from 'gulp-useref';\nimport gulpif from 'gulp-if';\nimport uglify from 'gulp-uglify';\nimport cleanCss from 'gulp-clean-css';\n\ngulp.task('html', () => {\n    return gulp.src('app/*.html')\n        .pipe(useref())\n        .pipe(gulpif('*.js', uglify()))\n        .pipe(gulpif('*.css', cleanCss()))\n        .pipe(gulp.dest('dist'));\n});\n\n// To run this task, ensure 'app/' contains at least one HTML file\n// with a build block, e.g., index.html:\n// <!-- build:css css/combined.css -->\n// <link href=\"css/one.css\" rel=\"stylesheet\">\n// <link href=\"css/two.css\" rel=\"stylesheet\">\n// <!-- endbuild -->\n// <!-- build:js scripts/combined.js -->\n// <script type=\"text/javascript\" src=\"scripts/one.js\"></script>\n// <script type=\"text/javascript\" src=\"scripts/two.js\"></script>\n// <!-- endbuild -->","lang":"javascript","description":"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."},"warnings":[{"fix":"Rewrite Gulp pipelines to directly pipe HTML streams to `useref()` without intermediate `assets()` calls. Refer to the v3 migration notes for examples.","message":"Version 3.0 introduced significant API changes, simplifying the overall usage. Previous methods like `useref.assets()` are no longer available.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"`gulp-useref` only handles concatenation and replacement of references in HTML. It does not perform minification, transpilation, or any other asset optimization itself.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"deprecated","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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()`.","cause":"This error typically occurs when migrating from `gulp-useref` v2 to v3 or later, where the `assets()` method was removed from the API.","error":"TypeError: useref.assets is not a function"},{"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.","cause":"`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.","error":"Error [ERR_REQUIRE_ESM] when using gulp-useref with ESM-only Gulp setup"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}