fingerprint-brunch

fingerprint-brunch

A Brunch plugin which renames assets with a SHA (generated from file content) to fingerprint it.

You're allowed to fingerprint specific files, assets folders, generated files and css linked assets.

• Installation
• Usage
• Options
• Testing / Issues
• Contributing

Installation

npm install fingerprint-brunch --save-dev

Usage

You can find here a working setup with fingerprint-brunch

Configuration

Optional You can override fingerprint-brunch's default options by updating your brunch-config.coffee with your custom parameters.

• manifest: (String) Defaults to ./assets.json
  • Mapping fingerprinted files
• srcBasePath: (String) Defaults to example/
  • The base Path you want to remove from the key string in the mapping file
• destBasePath: (String) Defaults to out/
  • The base Path you want to remove from the value string in the mapping file
• hashLength: (Integer) Defaults to 8
  • How many digits of the SHA1
• autoClearOldFiles: (Boolean) Defaults to false
  • Remove old fingerprinted files (usefull in development env)
• targets: (String|Array) Defaults to *
  • Files you want to hash, default is all if not you can put an array of files in your joinTo like ['app.js', 'vendor.js', ...]
• environments: (Array) Defaults to ['production']
  • Environment to fingerprint files
• alwaysRun: (Boolean) Defaults to false
  • Force fingerprint-brunch to run in all environments when true.
• autoReplaceAndHash: (Boolean) Defaults to false
  • Find assets in your jointTo files. It will be finded with url('path/to/assets.jpg') in your css (for now)
• assetsPrefix: (Boolean|String) Defaults to false
  • Prefix to prepend to replaced assets path.
• publicRootPath: (string) Defaults to /public
  • For support multiple themes, you can set the public root path, exemple :
  • My config.paths.public is ../../public/theme/theme-1/ in css your fonts, images will be linked like that : /theme/theme-1/img/troll.png.
  • You must set publicRootPath with ../../public to conserve correct link in your css..
• manifestGenerationForce: (Boolean) Defaults to false
  • Force the generation of the manifest, event if there are no fingerprinted files
• foldersToFingerprint: (Boolean|String|Array) Defaults to false
  • Asset to fingerprint (in brunch config public), all files will be fingerprinted and added to the manifest
  • Usage : '/img' or ['/img', '/svg']
• assetsToFingerprint: (Boolean|Array) Defaults to false
  • Specific asset to fingerprint (in public)
  • Usage : ['/img/troll.png'] or ['/img/troll.png', '/svg/logo.svg']
• assetsPatterns: (RegExp Object) Defaults to new RegExp(/url\([\'\"]?[a-zA-Z0-9\-\/_.:]+\.(woff|woff2|eot|ttf|otf|jpg|jpeg|png|bmp|gif|svg)\??\#?[a-zA-Z0-9\-\/_]*[\'\"]?\)/g)
  • Regex to match assets in css with url() attribute
• paramettersPattern: (Regex) Defaults to /(\?|\&|\#)([^=]?)([^&]*)/gm
  • Match hash and parameters in an URL

Example

exports.config =
  # ...
  plugins:
    fingerprint:
      manifest: './assets.json'
      srcBasePath: './exemple/'
      destBasePath: './out/'
      hashLength: 8
      autoClearOldFiles: false
      targets: '*'
      environments: ['production']
      alwaysRun: false
      autoReplaceAndHash: false
      publicRootPath: './public'
      manifestGenerationForce: false
      foldersToFingerprint: false
      assetsToFingerprint: false

The Manifest

{
  "css/master.css": "css/master-364b42a1.css",
  "js/master.js": "js/master-cb60c02b.js",
  "img/troll.png": "img/troll-5f2d5cbe.png",
  "fonts/font.eot": "fonts/font-45d860a3.eot",
  "fonts/font.woff": "fonts/font-6ced13b9.woff",
  "fonts/font.ttf": "fonts/font-82c653e7.ttf",
  "fonts/font.svg": "fonts/font-52343d4f.svg"
}

Fingerprint All

To get this kind of result in your manifest you need to :

• Set autoReplaceAndHash to true
• Or set foldersToFingerprint pointing to one folder ./img, or many ['./img', './svg']
• Or set assetsToFingerprint pointing to files ['./img/troll.png']

Cleaning Manifest

Use srcBasePath and destBasePath to remove some part of path files in the manifest.

Options

assetsPrefix

Sometimes you may want to add a prefix to assets when replacing their path in your compiled css/js.

Say you have a CSS file containing:

.logo {
  background-image: url('logo.svg');
}

once replaced, the content would look like:

.logo {
  background-image: url('logo-f98d59ab3.svg');
}

if you were to set assetsPrefix: '/custom/' the result would be:

.logo {
  background-image: url('/custom/logo-f98d59ab3.svg');
}

Note: This could also be leveraged to prepend a CDN url for instance.

Testing / Issues

Run npm i && npm test

Contributing

Pull requests are welcome. If you add functionality, then please add unit tests to cover it.