Static asset revisioning by appending content hash to filenames
unicorn.css
→unicorn-d41d8cd98f.css
This project is feature complete. PRs adding new features will not be accepted.
Make sure to set the files to never expire for this to have an effect.
$ npm install --save-dev gulp-rev
import gulp from 'gulp';
import rev from 'gulp-rev';
export default () => (
gulp.src('src/*.css')
.pipe(rev())
.pipe(gulp.dest('dist'))
);
Type: string
Default: 'rev-manifest.json'
Manifest file path.
Type: object
Type: string
Default: process.cwd()
Override the base
of the manifest file.
Type: string
Default: process.cwd()
Override the current working directory of the manifest file.
Type: boolean
Default: false
Merge existing manifest file.
Type: object
Default: JSON
An object with parse
and stringify
methods. This can be used to provide a
custom transformer instead of the default JSON
for the manifest file.
Original file paths are stored at file.revOrigPath
. This could come in handy for things like rewriting references to the assets.
The hash of each rev'd file is stored at file.revHash
. You can use this for customizing the file renaming, or for building different manifest formats.
import gulp from 'gulp';
import rev from 'gulp-rev';
export default () => (
// By default, Gulp would pick `assets/css` as the base,
// so we need to set it explicitly:
gulp.src(['assets/css/*.css', 'assets/js/*.js'], {base: 'assets'})
.pipe(gulp.dest('build/assets')) // Copy original assets to build dir
.pipe(rev())
.pipe(gulp.dest('build/assets')) // Write rev'd assets to build dir
.pipe(rev.manifest())
.pipe(gulp.dest('build/assets')) // Write manifest to build dir
);
An asset manifest, mapping the original paths to the revisioned paths, will be written to build/assets/rev-manifest.json
:
{
"css/unicorn.css": "css/unicorn-d41d8cd98f.css",
"js/unicorn.js": "js/unicorn-273c2c123f.js"
}
By default, rev-manifest.json
will be replaced as a whole. To merge with an existing manifest, pass merge: true
and the output destination (as base
) to rev.manifest()
:
import gulp from 'gulp';
import rev from 'gulp-rev';
export default () => (
// By default, Gulp would pick `assets/css` as the base,
// so we need to set it explicitly:
gulp.src(['assets/css/*.css', 'assets/js/*.js'], {base: 'assets'})
.pipe(gulp.dest('build/assets'))
.pipe(rev())
.pipe(gulp.dest('build/assets'))
.pipe(rev.manifest({
base: 'build/assets',
merge: true // Merge with the existing manifest if one exists
}))
.pipe(gulp.dest('build/assets'))
);
You can optionally call rev.manifest('manifest.json')
to give it a different path or filename.
Because of the way gulp-concat
handles file paths, you may need to set cwd
and path
manually on your gulp-concat
instance to get everything to work correctly:
import gulp from 'gulp';
import rev from 'gulp-rev';
import sourcemaps from 'gulp-sourcemaps';
import concat from 'gulp-concat';
export default () => (
gulp.src('src/*.js')
.pipe(sourcemaps.init())
.pipe(concat({path: 'bundle.js', cwd: ''}))
.pipe(rev())
.pipe(sourcemaps.write('.'))
.pipe(gulp.dest('dist'))
);
Since the order of streams are not guaranteed, some plugins such as gulp-concat
can cause the final file's content and hash to change. To avoid generating a new hash for unchanged source files, you can:
- Sort the streams with gulp-sort
- Filter unchanged files with gulp-unchanged
- Read more about incremental builds
This plugin does not support streaming. If you have files from a streaming source, such as Browserify, you should use gulp-buffer
before gulp-rev
in your pipeline:
import gulp from 'gulp';
import browserify from 'browserify';
import source from 'vinyl-source-stream';
import buffer from 'gulp-buffer';
import rev from 'gulp-rev';
export default () => (
browserify('src/index.js')
.bundle({debug: true})
.pipe(source('index.min.js'))
.pipe(buffer())
.pipe(rev())
.pipe(gulp.dest('dist'))
);
For more info on how to integrate gulp-rev
into your app, have a look at the integration guide.
It may be useful - and necessary - to use gulp-rev
with other packages to complete the task.
- gulp-rev-rewrite - Rewrite occurrences of filenames which have been renamed
- gulp-rev-css-url - Override URLs in CSS files with the revved ones
- gulp-rev-outdated - Old static asset revision files filter
- gulp-rev-collector - Static asset revision data collector
- rev-del - Delete old unused assets
- gulp-rev-delete-original - Delete original files after rev
- gulp-rev-dist-clean - Clean up temporary and legacy files created by gulp-rev
- gulp-rev-loader - Use rev-manifest with webpack
- gulp-rev-format - Provide hash formatting options for static assets (prefix, suffix, last-extension)
- gulp-rev-sri - Add subresource integrity field to rev-manifest