gulp-rev-urls
Gulp plugin for replacing URLs based on a manifest, especially well-suited for revving asset URLs. Handles relative URLs and is compatible with virtually any manifest format e.g. gulp-rev
or gulp-hasher
.
https://github.com/twadzilla/gulp-rev-urls
Install:
npm install --save-dev gulp-rev-urls
Usage:
var revUrls = ;var urlOptions = manifest: 'manifest.json';gulp
Note: this plugin does not support streaming.
Options
Note: In callback functions, settings
refers to the default options, overridden by any given options.
object | string
options.manifest : Maps original URLs to revised URLs. If passed as a string, manifest
is interpreted as a file path and parsed into an object with options.parse
.
Typically, URLs should be formatted as root-relative, i.e. begin with /
, or absolute:
"/img/foo.jpg": "/img/foo-bar.jpg" "/css/foo.css": "/css/foo.css?bar" "/a/b/c": "/d/e" "/foo/bar": "http://foo/bar"
When manifest
requires some alteration prior to replacing URLs, use options.transform
.
Defaults to: {}
function (contents, settings) : object
options.parse : Parses the contents of the file specified by options.manifest
into an object.
Defaults to: JSON.parse
function (object, key, value, settings) : void
options.transform : Applies transformation function for each key-value pair in options.manifest
. The supplied function should create a new entry in object
corresponding to key
and value
.
See examples below for handling manifests generated by gulp-rev
and gulp-hasher
.
Defaults to: null
RegExp
options.pattern : Identifies URLs in source text that may require revision. The contents of each file is searched for pattern
and the first non-empty capture group is passed to options.revise
for replacement. Thus pattern
should contain at least one capture group.
Defaults to: /(?:url\(["']?(.+?)['"]?\)|\s(?:src|href)=["'](.+?)['"])/g
function (originalUrl, expandedUrl, manifest, settings) : string
options.revise : Revises and returns a single URL that matched a capture group of options.pattern
. To retain the original URL, simply return originalUrl
.
The expandedUrl
argument reflects the root-relative or absolute originalUrl
after resolving any relative path segments i.e. ..
or .
.
For example, to preserve relative URLs and the query string/hash:
var urlOptions = manifest: '/foo/bar.jpg': '/foo/bar-12345678.jpg' { objkey = val; } { var revUrl = manifestfullPath; if revUrl var origParts = origUrl; var origPath = origParts; var origBase = origPath; return origBase + revUrl + origParts; return origUrl; }
Defaults to: manifest[fullUrl] || origUrl
string
options.docRoot : File path to the document root, i.e. the URL /
.
Defaults to: file.base
boolean
options.debug : When true, verbose logs are printed to console.
Defaults to: false
Examples
Complete example with gulp-rev
:
var gulp = ;var minifyCss = ;var uglify = ;var htmlmin = ;var hasher = ;var revUrls = ; var urlOptions = manifest: 'dist/rev-manifest.json' docRoot: 'src/public' // Converts relative file path to root-relative URL { var slash = key; objkey = val; } ; gulp; gulp; gulp; gulp;
A complete example with gulp-hasher
:
var gulp = ;var minifyCss = ;var uglify = ;var htmlmin = ;var hasher = ;var revUrls = ;var path = ;var url = ; var urlOptions = manifest: hasherhashes docRoot: 'src/public' // Converts absolute file paths to root-relative URLs // and appends content hash as query string { var rootRelUrl = url; objrootRelUrl = rootRelUrl + '?' + val; } ; gulp; gulp; gulp; gulp;
License
MIT @ Dave Twaddell