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
  • Configuration
  • Example
  • The manifest
  • Special features
    • Fingerprint All
    • Cleaning Manifest
  • Options
• Testing / Issues
• Contribution & Support
• Changelog
• Tip

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.js with your custom parameters.

• manifest: (String) Defaults to ./assets.json
  • Mapping file {generatedFileName: generatedFileNameWithHash}
• srcBasePath: (String) Defaults to ./example/
  • The base path you want to remove from the key string in the manifest
• destBasePath: (String) Defaults to ./out/
  • The base path you want to remove from the value string in the manifest
• hashLength: (Integer) Defaults to 8
  • How long the hash will be
• 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 (*), else put an array of files like ['app.js', 'vendor.js', ...]
• environments: (Array) Defaults to ['production']
  • Environment in which you want to fingerprint files
• alwaysRun: (Boolean) Defaults to false
  • Force fingerprint-brunch to run in all environments
• autoReplaceAndHash: (Boolean) Defaults to false
  • AutoReplaceAndHash assets in css/js, e.g. a font / image linked in an url() in your css
• assetsPrefix: (Boolean|String) Defaults to false
  • Prefix to prepend to assets replaced in css/js files
• publicRootPath: (string) Defaults to ./public
  • Public root location
• manifestGenerationForce: (Boolean) Defaults to false
  • Force the generation of the manifest, event if there are no fingerprinted files, in such case the manifest will contains an empty object
• foldersToFingerprint: (Boolean|String|Array) Defaults to false
  • Asset to fingerprint (inside /public), files will be fingerprinted and added to the manifest, this property can also be a string: '/img' or an array ['/img', '/svg']
• assetsToFingerprint: (Boolean|Array) Defaults to false
  • Specific asset to fingerprint (inside /public), can an array ['/img/troll.png', '/svg/logo.svg']
• assetsPattern: (RegExp Object) Defaults to /url\(['"]?[\w\-/.:]+\.(woff|woff2|eot|ttf|otf|jpg|jpeg|png|bmp|gif|svg)\??#?[\w\-/]*['"]?\)/g
  • Assets regex pattern
• paramettersPattern: (Regex) Defaults to /([#&?])([^=]?)([^&]*)/gm
  • URL parameters regex pattern, default authorized chars: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=

Check the plugin in details in the API documentation.

Example

exports.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"
}

Special features

Fingerprint All

This plugin allows you to fingerprint automatically all assets, direct, nested , etc. To enable this, please set your configuration like the following:

• Set autoReplaceAndHash to true.
• Or set foldersToFingerprint pointing to one folder ./img, or many ['./img', './svg'], you need to specify them anyway.
• Or set assetsToFingerprint pointing to files ['./img/troll.png'] if you want to fingerprint one or many specific files.

Cleaning Manifest

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

Options

Asset Prefixing

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 & Coverage

To execute the tests, run npm test and to test and coverage the code run npm run test:report.

Contribution & Support

Please read the the contributing guide and the code of conduct before submitting an issue.

Changelog

You can see the changelogs here.

Tip

If this project helped you in any way, you can always leave me a tip here:

BTC 36eHnxCRUDfWNFEx3YebRGw12WeutjkBBt

ETH 0x0F8b4F026624150e9F6267bFD93C372eb98e3010