npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gulp-html-replace

v1.6.2

Published

Replace build blocks in HTML. Like useref but done right.

Downloads

76,614

Readme

gulp-html-replace NPM version Travis AppVeyor Coverage Status

Replace build blocks in HTML. Like useref but done right.  

Table of Contents

Usage

Install:

npm install --save-dev gulp-html-replace

Put some blocks in your HTML file:

<!-- build:<name> -->
Everything here will be replaced
<!-- endbuild -->

name is the name of the block. Could consist of letters, digits, underscore ( _ ) and hyphen ( - ) symbols.

API

htmlreplace(tasks, options)

tasks

Type: Object {task-name: replacement}

  • task-name - The name of the block in your HTML.
  • replacement - String|Array|stream.Readable|Object The replacement. See examples below.
Simple example:
// Options is a single string
htmlreplace({js: 'js/main.js'})

// Options is an array of strings
htmlreplace({js: ['js/monster.js', 'js/hero.js']})

If your options strings ends with .js or .css they will be replaced by correct script/style tags, so you don't need to specify a template like in the example below.

Advanced example:
// Options is an object
htmlreplace({
  js: {
    src: 'img/avatar.png',
    tpl: '<img src="%s" align="left" />'
  }
})

// Multiple tag replacement
htmlreplace({
  js: {
    src: [['data-main.js', 'require-src.js']],
    tpl: '<script data-main="%s" src="%s"></script>'
  }
})
  • src - String|Array|stream.Readable Same thing as in simple example.
  • tpl - String Template string. Uses util.format() internally.

In the first example %s will be replaced with img/avatar.png producing <img src="img/avatar.png" align="left"> as the result.

In the second example data-main="%s" and src="%s" will be replaced with data-main.js and require-src.js accordingly, producing <script data-main="data-main.js" src="require-src.js"></script> as the result

Extended replacements:
// Replacement based on the file being processed
htmlreplace({
  js: {
    src: null,
    tpl: '<script src="%f".js></script>'
  }
})
// Extended replacement combined with standard replacement
htmlreplace({
  js: {
    src: 'dir',
    tpl: '<script src="%s/%f".js"></script>'
  }
})
  • src - null|String|Array|stream.Readable Same as examples above but null if there are no standard replacements in the template.
  • tpl - String Template string. Extended replacements do not use util.format() and are performed before standard replacements.

In the first example src is null because there are no standard replacements. %f is replaced with the name (without extension) of the file currently being processed. If the file being processed is xyzzy.html the result is <script src="xyzzy.js"></script>.

In the second example src has been set to the string 'dir'. Extended replacements are processed first, replacing %f with xyzzy, then %s will be replaced with dir resulting in <script src="dir/xyzzy.js"></script>.

Valid extended replacements are:

  • %f - this will be replaced with the filename, without an extension.
  • %e - this will be replaced with the extension including the . character.
Stream replacements:

Everywhere a string replacement can be given, a stream of vinyl is also accepted. The content of each file will be treated as UTF-8 text and used for replacement. If the stream produces more than a file the behavior is the same as when an array is given.

// Replacement is a stream
htmlreplace({
  cssInline: {
    src: gulp.src('style/main.scss').pipe(sass()),
    tpl: '<style>%s</style>'
  }
})

options

Type: object

All false by default.

  • {Boolean} keepUnassigned - Whether to keep blocks with unused names or remove them.
  • {Boolean} keepBlockTags - Whether to keep <!-- build --> and <!-- endbuild --> comments or remove them.
  • {Boolean} resolvePaths - Try to resolve relative paths. For example if your cwd is /, your html file is /page/index.html and you set replacement as lib/file.js the result path in that html will be ../lib/file.js
Options example:
htmlreplace({
  js: {
    src: null,
    tpl: '<script src="%f".js></script>'
  }
}, {
  keepUnassigned: false,
  keepBlockTags: false,
  resolvePaths: false
})

Example

index.html:

<!DOCTYPE html>
<html>
    <head>

    <!-- build:css -->
    <link rel="stylesheet" href="css/normalize.css">
    <link rel="stylesheet" href="css/main.css">
    <!-- endbuild -->

    </head>
    <body>

    <!-- build:js -->
    <script src="js/player.js"></script>
    <script src="js/monster.js"></script>
    <script src="js/world.js"></script>
    <!-- endbuild -->

gulpfile.js:

var gulp = require('gulp');
var htmlreplace = require('gulp-html-replace');

gulp.task('default', function() {
  gulp.src('index.html')
    .pipe(htmlreplace({
        'css': 'styles.min.css',
        'js': 'js/bundle.min.js'
    }))
    .pipe(gulp.dest('build/'));
});

Result:

<!DOCTYPE html>
<html>
    <head>

    <link rel="stylesheet" href="styles.min.css">

    </head>
    <body>

    <script src="js/bundle.min.js"></script>

Upgrade

From 0.x to 1.x

This version introduces streaming support, less confusing API, new option keepUnused and full code overhaul.

  • If you used single task like this: htmlreplace('js', 'script.js') just change it to htmlreplace({js: 'script.js'})
  • If you used single task with template: htmlreplace('js', 'script.js', '<script="%s">') change it to htmlreplace({js: {src: 'script.js', tpl: '<script="%s">'})
  • files renamed to src, see previous example. Rename if needed.

From 1.1.x to 1.2.x

This version switches to the new way of specifying options which is more future-proof. Before it was htmlreplace(tasks, keepUnassigned = false), now it's htmlreplace(tasks, {keepUnassigned: false}). No action required, old syntax will still work, but it is advisable to switch to the new syntax.