gulp-assets-version-replace

Gulp plugin for managing version of assets, easy to build new version to commit and deploy.

Features

Generate new file for js,css etc. based on md5 of file contents
Create new version only for changed assets
Auto replace versioned assets in template files, like php, python Django, Expressjs ejs and etc.

Examples

1. File structure

Assets structure：

js_build/app.js
css_build/webapp.css

Files under js_build and css_build are generated by compass uglify

Links in templates：

<link href="static/dist/css_build/webapp.__placeholder__.css" />

Note: __placeholder__ is a placeholder when it has not been versioned yet

2. Configs in gulpfile.js：

gulp.task('assetsVersionReplace', function () {
  gulp.src(['css_build/*.css', 'js_build/*.js'])
    .pipe(assetsVersionReplace({
      replaceTemplateList: [
        'php-templates/header.php',
        'php-templates/footer.php'
      ]
    }))
    .pipe(gulp.dest('dist/'))
});

3. Run gulp task

gulp assetsVersionReplace in your terminal.

Your get these result:

Files named with generated version

dist/js_build/app.c7ccb6b8ce569a65ed09d4256e89ec30.js
dist/css_build/webapp.2af81cda4dacbd5d5294539474076aae.css

Links in templates have been replaced with generated version

<link href="static/dist/css_build/webapp.2af81cda4dacbd5d5294539474076aae.css" />

4. Commit

The changes of template contain version string, commit directly if you are deployoing a static site.

More Example

In some case templates are created by other gulp task before replacing version string. versionsAmount: 0 option is introduced for this reason.
See following example, the templates in the dist folder are always have __placeholder__ as they are copied from dev folder each time run gulp task. Setting versionsAmount: 0 will make version replacing works in this case.

gulp.task('copyTemplates', function () {
  return gulp.src('php-templates-dev/*.php')
        .pipe(usemin({
            jsmin: uglify()
        }))
        .pipe(gulp.dest('php-templates-dist'));
})
gulp.task('assetsVersionReplace', ['copyTemplates'], function () {
  return gulp.src(['css_build/*.css', 'js_build/*.js'])
    .pipe(assetsVersionReplace({
      versionsAmount: 0,
      replaceTemplateList: [
        'php-templates-dist/header.php',
        'php-templates-dist/footer.php'
      ]
    }))
    .pipe(gulp.dest('dist/'))
});

Gulp4 Example

A gulp4 example of using this plugin is here: gulp-workflow

Install

npm install gulp-assets-version-replace --save-dev

In your gulpfile.js place this line:

var assetsVersionReplace = require('gulp-assets-version-replace');

A json file called gulp-assets-version-replace-version.json will be created beside your gulpfile.js to store versions.

Form asset link as following in your template:

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <title>test</title>
  <link href="static/dist/css_build/app.__placeholder__.css" />
  <link href="static/dist/css_build/desktop.__placeholder__.css" />
</head>
<body>

Notes: __placeholder__ is a placeholder for replacing with generated versions at first time

Gulp Plugin Options

options.versionsAmount

How many versions to keep in your local json file. Set 0 to disable local save.

options.replaceTemplateList

List of templates which contain assets links of tsFiles . Support whatever extension like php, python Django, Express and etc. Make sure give templates paths relative to gulpfile.js.

Optional: true Value Type: Array Default Value: []

Release History

2015-12-19 v2.1.0 More stable now
2015-12-16 v2.0.0 More standard for gulp pipe
2015-12-15 v1.0.0