Registry / devops / gulp-html-replace

gulp-html-replace

JSON →
library1.6.2jsnpmunverified

gulp-html-replace is a Gulp plugin designed for replacing HTML "build blocks" with specified content during a build process. It functions similarly to `useref` but aims for a more robust and correct implementation. The current stable version is 1.6.2. Releases appear to be somewhat infrequent but consistent, primarily focusing on bug fixes, performance improvements to the parsing engine, and minor enhancements. Key differentiators include its flexible replacement patterns, supporting simple strings, arrays of strings, objects with `src` and `tpl` for advanced formatting, and even Vinyl file streams as input. It also offers extended replacements for injecting the current filename (`%f`) and file extension (`%e`) into custom templates.

devops
npm install gulp-html-replace
github ↗package ↗
INSTALL
IMPORT
SIG · GULP-HTML-REPLACE
G
gulp-html-replace
devopsjavascriptv1.6.2
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.

htmlreplace
✓ const htmlreplace = require('gulp-html-replace');
✗ import htmlreplace from 'gulp-html-replace';
Gulp plugins, including `gulp-html-replace`, are typically consumed via CommonJS `require` in `gulpfile.js` files, which traditionally run in a Node.js CJS environment. ESM imports are generally not used for Gulp tasks directly.

This quickstart demonstrates a full Gulp build process using `gulp-html-replace`. It includes tasks for minifying and concatenating CSS and JavaScript, then a `processHtml` task that uses `gulp-html-replace` to update HTML build blocks with references to the processed assets. It shows simple string, array, object with template, and stream-based replacements, as well as extended filename (`%f`) replacements.

const gulp = require('gulp'); const htmlreplace = require('gulp-html-replace'); const concat = require('gulp-concat'); const uglify = require('gulp-uglify'); const cleanCss = require('gulp-clean-css'); // Example source HTML with build blocks in `src/index.html`: // <!-- build:css --> // <link rel="stylesheet" href="css/unoptimized.css"> // <!-- endbuild --> // <!-- build:js --> // <script src="js/lib1.js"></script> // <script src="js/lib2.js"></script> // <!-- endbuild --> // <!-- build:inline_svg --> // <svg></svg> // <!-- endbuild --> function styles() { return gulp.src('src/css/**/*.css') .pipe(cleanCss()) .pipe(concat('bundle.min.css')) .pipe(gulp.dest('dist/css')); } function scripts() { return gulp.src('src/js/**/*.js') .pipe(uglify()) .pipe(concat('bundle.min.js')) .pipe(gulp.dest('dist/js')); } function processHtml() { return gulp.src('src/index.html') .pipe(htmlreplace({ css: 'css/bundle.min.css', // Simple string replacement js: ['js/vendor.min.js', 'js/app.min.js'], // Array of strings replacement inline_svg: { // Advanced object replacement with inline content src: gulp.src('src/assets/icon.svg'), // Stream replacement tpl: '<div id="icon-container">%s</div>' }, // Example of extended replacement using filename filename_ref: { src: null, // No standard replacement, only extended tpl: '<a href="/docs/%f.pdf">View Documentation</a>' } }, { keepUnassigned: false // Example option: remove blocks without a match })) .pipe(gulp.dest('dist')); } exports.build = gulp.series(gulp.parallel(styles, scripts), processHtml);
Debug
Known issues
breakingThe parsing engine for `gulp-html-replace` was completely rewritten in v1.5.0. While intended to fix issues related to HTML formatting and line endings, this significant change might alter behavior for edge cases or specific HTML structures that previous versions may have handled differently (even if imperfectly), potentially breaking existing build pipelines.
fix
Thoroughly test HTML processing pipelines after upgrading to v1.5.0 or later, especially for complex or malformed HTML structures. Review the output HTML carefully for any unexpected changes or regressions in block replacement.
affects: >=1.5.0
gotchaPrior to v1.5.3, `gulp-html-replace` relied on `file.dirname` for path resolution, which is only consistently available in `vinyl@0.5.0` and newer. Using older versions of `vinyl` with `gulp-html-replace` versions before 1.5.3 could lead to incorrect path resolution or errors during file processing.
fix
Ensure your Gulp setup uses `vinyl@0.5.0` or newer, or upgrade `gulp-html-replace` to v1.5.3 or later. Version 1.5.3 implemented a fix to use `path.dirname` for broader compatibility across `vinyl` versions.
affects: <1.5.3
gotchaWhen providing simple string replacements for `.js` or `.css` files (e.g., `htmlreplace({ js: 'bundle.js' })`), the plugin automatically generates standard `<script>` or `<link rel="stylesheet">` tags. For other file types, custom HTML attributes, or different tag structures, you *must* provide a `tpl` (template) string in an object replacement.
fix
For non-JS/CSS replacements or when you need custom HTML attributes or tag structures, always use the object format: `htmlreplace({ block: { src: 'path/to/file', tpl: '<custom-tag src="%s" type="module"></custom-tag>' } })`.
affects: all
gotchaThe block name in your HTML comment (e.g., `<!-- build:<name> -->`) must precisely match the corresponding key in the `tasks` object passed to `htmlreplace()`. Mismatched names will result in the block not being replaced. If the `keepUnassigned` option is `true`, these unmatched blocks will remain in the output.
fix
Ensure strict case-sensitive matching between the block name in your HTML comments (e.g., `<!-- build:my-custom-block -->`) and the key in the `tasks` object (e.g., `{ 'my-custom-block': 'replacement' }`). Always double-check block names for typos.
affects: all
Errors
Common errors & fixes
TypeError: htmlreplace is not a function
The `require()` statement for `gulp-html-replace` failed, or the imported module was assigned to an incorrect variable, or Gulp itself is not properly configured.
fix
Ensure `const htmlreplace = require('gulp-html-replace');` is at the top of your `gulpfile.js` and that Gulp is installed and running correctly. Verify the package name in `require()` matches the installed package.
Error: Replacement for block 'my-block' is missing or invalid.
The replacement value provided in the `tasks` object for a specific block is either `undefined`, `null` when a `src` is expected for a template, or not a valid string, array, object, or Vinyl stream.
fix
Check the `tasks` object passed to `htmlreplace()` and ensure each block name has a valid corresponding replacement value (string, array of strings, object with `src` and `tpl`, or a Vinyl stream) as per the API documentation.
HTML block '<!-- build:unmatched-block -->...<!-- endbuild -->' was not replaced.
The name specified in the HTML build block comment does not correspond to any key in the `tasks` object passed to `htmlreplace()`. This happens when `keepUnassigned` option is `false` (the default), but the block still appears, or when `keepUnassigned` is `true` and the block remains.
fix
Verify that the block name in your HTML (e.g., `unmatched-block`) precisely matches a key in your `htmlreplace` tasks object. If `keepUnassigned` is `true`, blocks without a match will intentionally remain in the output.
The 'callback' argument must be a function (when using tpl with util.format internally)
This error can occur if the `tpl` property in an advanced replacement object is not a string, or if the number of `%s` placeholders in the `tpl` string does not match the number of elements in the `src` array/string.
fix
Ensure that the `tpl` property is always a string. Additionally, verify that the count of `%s` placeholders in the `tpl` string exactly matches the number of items provided in the `src` array (or one `%s` if `src` is a single string).
Upgrade
Version history
1.6.2latest on npm
Audit
Dependencies
gulprequiredRuntime dependency for Gulp task execution. As a Gulp plugin, it requires Gulp to be installed and used in the project.
Agent activity
7 hits · last 30 days
node
6
Perplexity
1
Resources
githubhttps://github.com/VFK/gulp-html-replace ↗
packagehttps://www.npmjs.com/package/gulp-html-replace ↗
gulp-html-replace — npm install gulp-html-replace · libregistry