Versioniser

Cache bust filenames by automatically incrementing them with version numbers stored in your .env file.

Installation

npm i @marknotton/versioniser --save-dev

const versioniser = require('@marknotton/versioniser');

Versioner refers to your .env file when storing version numbers for filename manipulation. If your server doesn't support environmental variables in the form of a local .env file, then Versioniser is not for you.

There are a few options to manage variables that are suffixed with "_VERSION" y. The purpose for this (and the reason I built this plugin), is to increment a variable each time a certain gulp task is called. Allowing me to generate unique file names for concatenated files. Ultimately this helps avoid browsers from caching old files whilst avoiding the use of ugly and unreliable url parameters.

Get Version [int]

Get the version number of a variable

versioniser.getVersion(variable)

Update Version [int]

Update the version number of a variable by incrementing the number by one.

Parameter	Type	Description
name	string	The name of the variable that prefixes the _VERSION variable
force	int	By default this function will increment by one. However, you can update a variable to a specific number.

versioniser.updateVersion(variable)

Get Version Name

To modify the filename for your gulp task, you will need to generate a dynamic name to match your latest version. This gives you that new filename.

Parameter	Type	Description
file	string	The original filename
variable	string	To find the latest version number, define the variable name to look for in the .env file. You do not need to include the suffix '_VERSION'
end	bool	Choose where the version number appears in the filename. This function looks for the FIRST full stop in the string, and prepends the version number to that. However there may be cases where there are multiple full stops in a string. Define true to explicitly prepend the version number to the LAST full stop in the string. This is true by default.

versioniser.getVersionName('main.min.js', 'js', true)

This will look for the JS_VERSION=12 in your .env file and return a string that looks like this

main.v12.min.js

If you set the end boolean to false, this would be returned instead:

main.min.v12.js

Update Version Name

This essentially does the exact same thing as getVersionName, only it will increment the version in the .env file before returning the name filename.

Delete Versions

Versioned files may start to get overwhelming and unnecessary. This lets you keep a set amount of versioned files.

Parameter	Type	Description
directory	string	Relative to your gulpfile.js, point to where your versioned files are stored.
original	string	Pass the original filename so the comparison can match files after the version number has be verified
keep	int	Define how many versions of your versioned files you want to keep. By default this is set to 5.

versioniser.deleteVersions('assets/js/', 'main.min.js', 3)

Credit

Couldn't have built this without gulp-dotenv. Thank you!