# gulp-html-replace

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

Latest version **1.6.2** (published 2016-11-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-html-replace
pnpm add gulp-html-replace
yarn add gulp-html-replace
bun add gulp-html-replace
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.6.2 |
| Published | 2016-11-18 |
| First published | 2014-02-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/gulp-html-replace) |
| Module format | CommonJS |
| Node | >= 0.9 |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Vladimir Kucherenko |
| Maintainers | vfk |
| Keywords | gulpplugin, html, replace |

## Links

- npm: https://www.npmjs.com/package/gulp-html-replace
- Repository: https://github.com/VFK/gulp-html-replace
- Homepage: https://github.com/VFK/gulp-html-replace#readme
- Issues: https://github.com/VFK/gulp-html-replace/issues
- npm.io page: https://npm.io/package/gulp-html-replace

## Dependencies (6)

- [clone](https://npm.io/package/clone.md) ^1.0.2
- [slash](https://npm.io/package/slash.md) ^1.0.0
- [bluebird](https://npm.io/package/bluebird.md) ^3.1.1
- [vinyl-buffer](https://npm.io/package/vinyl-buffer.md) ^1.0.0
- [object-assign](https://npm.io/package/object-assign.md) ^4.0.1
- [readable-stream](https://npm.io/package/readable-stream.md) ^2.0.4

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 1.6.2 (latest) — 2016-11-18
- 1.6.1 — 2016-06-17
- 1.6.0 — 2016-05-28
- 1.5.5 — 2015-11-21
- 1.5.4 — 2015-09-22
- 1.5.3 — 2015-09-18
- 1.5.2 — 2015-09-17
- 1.5.1 — 2015-06-29
- 1.5.0 — 2015-06-03
- 1.4.5 — 2015-04-11
- 1.4.4 — 2015-02-02
- 1.4.3 — 2015-01-17
- 1.4.2 — 2015-01-13
- 1.4.1 — 2014-10-23
- 1.4.0 — 2014-10-13
- … 9 more at https://npm.io/package/gulp-html-replace/versions

## README

# gulp-html-replace [![NPM version][npm-image]][npm-url] [![Travis][travis-image]][travis-url] [![AppVeyor][appveyor-image]][appveyor-url] [![Coverage Status][coveralls-image]][coveralls-url]

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

### Table of Contents

- [Usage](#usage)
- [API](#api)
- [Example](#example)
- [Upgrade](#upgrade)


## Usage
Install:
```shell
npm install --save-dev gulp-html-replace
```

Put some blocks in your HTML file:
```html
<!-- 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:
```javascript
// 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:
```javascript
// 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()](http://nodejs.org/api/util.html#util_util_format_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:
```javascript
// 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.
```javascript
// 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:
```javascript
htmlreplace({
  js: {
    src: null,
    tpl: '<script src="%f".js></script>'
  }
}, {
  keepUnassigned: false,
  keepBlockTags: false,
  resolvePaths: false
})
```

## Example
index.html:

```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:

```javascript
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:

```html
<!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.

[npm-url]: https://npmjs.org/package/gulp-html-replace
[npm-image]: http://img.shields.io/npm/v/gulp-html-replace.svg
[travis-url]: https://travis-ci.org/VFK/gulp-html-replace
[travis-image]: https://travis-ci.org/VFK/gulp-html-replace.svg
[appveyor-url]: https://ci.appveyor.com/project/VFK/gulp-html-replace
[appveyor-image]: https://ci.appveyor.com/api/projects/status/66kwbnis5a1gwp6d?svg=true
[coveralls-url]: https://coveralls.io/github/VFK/gulp-html-replace?branch=master
[coveralls-image]: https://coveralls.io/repos/VFK/gulp-html-replace/badge.svg?branch=master&service=github

---
_Source: https://npm.io/package/gulp-html-replace · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._