gulp-useref
A Gulp plugin that parses HTML build blocks to concatenate and replace references to scripts and stylesheets.
What is gulp-useref?
gulp-useref is a Gulp plugin that parses HTML files to replace references to multiple non-optimized JavaScript and CSS files with concatenated, optimized versions. It automates the process of combining assets during build time, reducing HTTP requests and improving frontend performance. The plugin uses special HTML comment blocks to define which files should be merged and where the output should be placed.
Frontend developers and build engineers using Gulp for task automation who need to optimize website assets by concatenating scripts and stylesheets.
Developers choose gulp-useref for its seamless integration with Gulp workflows, stream-based processing that enables further transformations, and its simplicity compared to manual concatenation or heavier build tools.
Overview
Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets.
Use Cases
Best For
- Automating concatenation of multiple JavaScript files in Gulp builds
- Combining CSS stylesheets to reduce HTTP requests in production
- Integrating asset optimization into existing Gulp task pipelines
- Processing HTML files with build blocks for conditional asset inclusion
- Stream-based asset transformation before deployment
- Replacing grunt-useref workflows in Gulp-based projects
Not Ideal For
- Projects using modern bundlers like Webpack, Rollup, or Vite that include built-in asset optimization
- Teams requiring a standalone tool for asset concatenation without the overhead of Gulp setup and maintenance
- Applications with server-side rendered content where assets are managed on the server-side or via framework-specific bundling
- Developers looking for an all-in-one solution that includes minification, tree-shaking, and code splitting out-of-the-box
Pros & Cons
Pros
Seamlessly fits into Gulp pipelines, allowing assets to be passed through for further transformations like minification with gulp-if, as shown in the usage examples with uglify and minifyCss.
Uses intuitive HTML comment blocks to define build targets, making it easy to specify which files to concatenate without complex configuration files, detailed in the block syntax section.
Supports customizable search paths and additional streams via options, enabling integration with preprocessing tools like TypeScript for enhanced workflow flexibility.
Automatically replaces multiple script and link tags in HTML with optimized versions, reducing manual effort and improving page load performance by decreasing HTTP requests.
Cons
Only concatenates files and requires additional plugins like gulp-if with gulp-uglify for minification, increasing setup complexity and dependency management.
Tied exclusively to Gulp, making it unsuitable for projects using other build tools or those transitioning to newer alternatives like npm scripts or modern bundlers.
Version 3 introduced significant API changes that broke existing implementations, forcing developers to rewrite gulpfiles, as highlighted in the migration notes with errors like 'useref.assets is not a function'.
Only processes HTML files with build blocks, so it doesn't handle asset optimization in other contexts like JavaScript modules or CSS-in-JS, limiting its scope in modern web development.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.