# useref
> Parse build blocks in HTML files to replace references
Latest version **1.4.4** (published 2022-03-27) · MIT license · 0 weekly downloads
## Install
```sh
npm install useref
pnpm add useref
yarn add useref
bun add useref
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.4.4 |
| Published | 2022-03-27 |
| First published | 2015-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 0 |
| Unpacked size | 16.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 51 |
| Author | Jonathan Kemp |
| Maintainers | jonkemp |
| Keywords | build, blocks, build, comments, replace, scripts, link, ref |
## Links
- npm: https://www.npmjs.com/package/useref
- Repository: https://github.com/jonkemp/useref
- Homepage: https://github.com/jonkemp/useref#readme
- Issues: https://github.com/jonkemp/useref/issues
- npm.io page: https://npm.io/package/useref
## Alternatives
- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads
## Recent versions
- 1.4.4 (latest) — 2022-03-27
- 1.4.3 — 2020-01-18
- 1.4.2 — 2019-10-05
- 1.4.1 — 2018-03-01
- 1.4.0 — 2017-11-20
- 1.3.1 — 2017-11-05
- 1.3.0 — 2017-10-10
- 1.2.0 — 2016-03-25
- 1.1.2 — 2016-01-07
- 1.1.1 — 2015-12-28
- 1.1.0 — 2015-11-23
- 1.0.0 — 2015-11-21
## README
# useref  [](https://coveralls.io/github/jonkemp/useref?branch=master)
[](https://nodei.co/npm/useref/)
> Parse build blocks in HTML files to replace references
Extracted from the grunt plugin [grunt-useref](https://github.com/pajtai/grunt-useref).
## Installation
```
npm install useref
```
## Usage
```js
var useref = require('useref');
var result = useref(inputHtml);
// result = [ replacedHtml, { type: { path: { 'assets': [ replacedFiles] }}} ]
```
Blocks are expressed as:
```html
... HTML Markup, list of script / link tags.
```
- **type**: either `js`, `css` or `remove`
- **alternate search path**: (optional) By default the input files are relative to the treated file. Alternate search path allows one to change that
- **path**: the file path of the optimized file, the target output
- **parameters**: extra parameters that should be added to the tag. By default `rel="stylesheet"` attribute is added to css link tag, your can overwrite it by passing your own rel parameter, e.g. `rel="preload"`
An example of this in completed form can be seen below:
```html
```
The module would be used with the above sample HTML as follows:
```js
var result = useref(sampleHtml);
// [
// resultHtml,
// {
// css: {
// 'css/combined.css': {
// 'assets': [ 'css/one.css', 'css/two.css' ]
// }
// },
// js: {
// 'scripts/combined.js': {
// 'assets': [ 'scripts/one.js', 'scripts/two.js' ]
// },
// 'scripts/async.js': {
// 'assets': [ 'scripts/three.js', 'scripts/four.js' ]
// }
// }
// }
// ]
```
The resulting HTML would be:
```html
```
## IE Conditional Comments
Internet Explorer Conditional Comments are preserved. The code below:
```html
```
Results in:
```html
```
### Custom blocks
Sometimes you need a bit more. If you would like to do custom processing, this is possible with a custom block, as demonstrated below.
```html
```
With
```js
var useref = require('useref');
var result = useref(inputHtml, {
// each property corresponds to any blocks with the same name, e.g. "build:import"
import: function (content, target, options, alternateSearchPath) {
// do something with `content` and return the desired HTML to replace the block content
return content.replace('bower_components', target);
}
});
```
Becomes
```html
```
The handler function gets the following arguments:
- *content* (String): The content of the custom use block
- *target* (String): The "path" value of the use block definition
- *options* (String): The extra attributes from the use block definition, the developer can parse as JSON or do whatever they want with it
- *alternateSearchPath* (String): The alternate search path that can be used to maintain a coherent interface with standard handlers
Include a handler for each custom block type.
### Symfony Twig and Laravel 5 Blade assets
Works with the [symfony2 assetic](http://symfony.com/doc/current/cookbook/assetic/asset_management.html) and [laravel asset](https://laravel.com/docs/5.1/helpers#method-asset) and [elixir](https://laravel.com/docs/5.2/elixir#versioning-and-cache-busting) links in twig or blade or html or php.
```html
```
### Options
#### options.noconcat
Type: `Boolean`
Default: `false`
Strips out build comments but leaves the rest of the block intact without replacing any tags.
```html
```
Results in:
```html
```
#### options.parseSourcePath
Type: `Function`
Return: The path to the source file
Function to parse the source path out of a script or style element.
The function gets the following arguments:
- *tag* (String): The html script or style tag
- *type*: (String): The type e.g. `js`, `css`
#### options.transformTargetPath
Type: `Function`
Return: The transformed path to the target file
Function to transform the target file path.
The function gets the following arguments:
- *target* (String): The path to the target file
- *type*: (String): The type e.g. `js`, `css`
## Contributing
See the [CONTRIBUTING Guidelines](https://github.com/jonkemp/useref/blob/master/CONTRIBUTING.md)
## License
MIT © [Jonathan Kemp](http://jonkemp.com)
---
_Source: https://npm.io/package/useref · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._