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
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 toexample/
- The base Path you want to remove from the
key
string in the mapping file
- The base Path you want to remove from the
- destBasePath: (
String
) Defaults toout/
- The base Path you want to remove from the
value
string in the mapping file
- The base Path you want to remove from the
- hashLength: (
Integer
) Defaults to8
- How many digits of the SHA1
- autoClearOldFiles: (
Boolean
) Defaults tofalse
- 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', ...]
- Files you want to hash, default is all if not you can put an array of files in your
- environments: (
Array
) Defaults to['production']
- Environment to fingerprint files
- alwaysRun: (
Boolean
) Defaults tofalse
- Force fingerprint-brunch to run in all environments when true.
- autoReplaceAndHash: (
Boolean
) Defaults tofalse
- Find assets in your
jointTo
files. It will be finded withurl('path/to/assets.jpg')
in your css (for now)
- Find assets in your
- assetsPrefix: (
Boolean|String
) Defaults tofalse
- 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/
incss
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 tofalse
- Force the generation of the manifest, event if there are no fingerprinted files
- foldersToFingerprint: (
Boolean|String|Array
) Defaults tofalse
- Asset to fingerprint (in brunch config
public
), all files will be fingerprinted and added to the manifest - Usage :
'/img'
or['/img', '/svg']
- Asset to fingerprint (in brunch config
- assetsToFingerprint: (
Boolean|Array
) Defaults tofalse
- Specific asset to fingerprint (in public)
- Usage :
['/img/troll.png']
or['/img/troll.png', '/svg/logo.svg']
- assetsPatterns: (
RegExp Object
) Defaults tonew 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
- Regex to match assets in css with
- 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
Fingerprint All
To get this kind of result in your manifest you need to :
- Set
autoReplaceAndHash
totrue
- 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:
once replaced, the content would look like:
if you were to set assetsPrefix: '/custom/'
the result would be:
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.