useref !Build Status 


> Parse build blocks in HTML files to replace references

Extracted from the grunt plugin 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

`

$3

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.

$3

Works with the symfony2 assetic and laravel asset and elixir links in twig or blade or html or php.

`html




`

$3

#### 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

License

MIT © Jonathan Kemp