{"id":13271,"library":"gulp-html-replace","title":"Gulp HTML Replace","description":"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.","status":"active","version":"1.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/VFK/gulp-html-replace","tags":["javascript","gulpplugin","html","replace"],"install":[{"cmd":"npm install gulp-html-replace","lang":"bash","label":"npm"},{"cmd":"yarn add gulp-html-replace","lang":"bash","label":"yarn"},{"cmd":"pnpm add gulp-html-replace","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for Gulp task execution. As a Gulp plugin, it requires Gulp to be installed and used in the project.","package":"gulp","optional":false}],"imports":[{"note":"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.","wrong":"import htmlreplace from 'gulp-html-replace';","symbol":"htmlreplace","correct":"const htmlreplace = require('gulp-html-replace');"}],"quickstart":{"code":"const gulp = require('gulp');\nconst htmlreplace = require('gulp-html-replace');\nconst concat = require('gulp-concat');\nconst uglify = require('gulp-uglify');\nconst cleanCss = require('gulp-clean-css');\n\n// Example source HTML with build blocks in `src/index.html`:\n// <!-- build:css -->\n// <link rel=\"stylesheet\" href=\"css/unoptimized.css\">\n// <!-- endbuild -->\n// <!-- build:js -->\n// <script src=\"js/lib1.js\"></script>\n// <script src=\"js/lib2.js\"></script>\n// <!-- endbuild -->\n// <!-- build:inline_svg -->\n// <svg></svg>\n// <!-- endbuild -->\n\nfunction styles() {\n  return gulp.src('src/css/**/*.css')\n    .pipe(cleanCss())\n    .pipe(concat('bundle.min.css'))\n    .pipe(gulp.dest('dist/css'));\n}\n\nfunction scripts() {\n  return gulp.src('src/js/**/*.js')\n    .pipe(uglify())\n    .pipe(concat('bundle.min.js'))\n    .pipe(gulp.dest('dist/js'));\n}\n\nfunction processHtml() {\n  return gulp.src('src/index.html')\n    .pipe(htmlreplace({\n      css: 'css/bundle.min.css', // Simple string replacement\n      js: ['js/vendor.min.js', 'js/app.min.js'], // Array of strings replacement\n      inline_svg: { // Advanced object replacement with inline content\n        src: gulp.src('src/assets/icon.svg'), // Stream replacement\n        tpl: '<div id=\"icon-container\">%s</div>'\n      },\n      // Example of extended replacement using filename\n      filename_ref: {\n        src: null, // No standard replacement, only extended\n        tpl: '<a href=\"/docs/%f.pdf\">View Documentation</a>'\n      }\n    }, {\n      keepUnassigned: false // Example option: remove blocks without a match\n    }))\n    .pipe(gulp.dest('dist'));\n}\n\nexports.build = gulp.series(gulp.parallel(styles, scripts), processHtml);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=1.5.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<1.5.3"},{"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>' } })`.","message":"When 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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: htmlreplace is not a function"},{"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.","cause":"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.","error":"Error: Replacement for block 'my-block' is missing or invalid."},{"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.","cause":"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.","error":"HTML block '<!-- build:unmatched-block -->...<!-- endbuild -->' was not replaced."},{"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).","cause":"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.","error":"The 'callback' argument must be a function (when using tpl with util.format internally)"}],"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}