webpack-auto-inject-version/README.md

274 lines
7.3 KiB
Markdown
Raw Normal View History

2016-10-21 19:04:52 +11:00
# Auto inject version - Webpack plugin
2017-04-11 09:11:09 +10:00
Adds version from package.json into every single file as top comment block.
2016-10-20 17:58:19 +11:00
2017-04-13 07:47:11 +10:00
# Install
2017-04-11 09:11:09 +10:00
```console
$ npm install webpack-auto-inject-version --save-dev
```
2017-04-13 07:47:11 +10:00
# Table of Contents
2017-04-13 07:50:14 +10:00
[What it does](#user-content-what-it-does) <br>
[How to use](#user-content-how-to-use) <br>
[Available options](#user-content-available-options) <br>
[Output examples](#user-content-output-examples)
2018-03-15 22:18:10 +11:00
[How to use with other webpack plugins](#user-content-how-to-use-with-other-webpack-plugins)<br>
[Change log](#user-content-change-log)<br>
2017-04-13 07:47:11 +10:00
# What it does
2016-10-21 18:32:35 +11:00
Auto Inject Version (AIV) can:
- inject version from package.json into every bundle file as a comment ( at the top )
2017-04-11 09:11:09 +10:00
- inject version from package.json into any place in your HTML by special tag `[AIV]{version}[/AIV]`
- inject version from package.json into any place in CSS/JS file by special tag `[AIV]{version}[/AIV]`
- auto increase package.json version by --env.major, --env.minor, --env.patch passed into webpack
2017-04-13 07:47:11 +10:00
# How to use
2018-10-28 04:59:02 +11:00
It's easy to set it up, all you need is:
* use WebpackAutoInject in webpack plugins
2017-04-13 07:47:11 +10:00
* pass config as a parameter, or leave it blank as all options are "on" by default.
2016-10-20 19:32:26 +11:00
### Simple config example ( in webpack.conf.js )
2017-04-13 07:47:11 +10:00
```js
var WebpackAutoInject = require('webpack-auto-inject-version');
...
2016-10-20 19:32:26 +11:00
module.exports = {
2017-04-13 07:47:11 +10:00
...
2016-10-20 17:58:19 +11:00
plugins: [
2017-04-11 09:11:09 +10:00
new WebpackAutoInject({
// options
// example:
components: {
AutoIncreaseVersion: false
}
})
2016-10-20 17:58:19 +11:00
]
2016-10-20 19:32:26 +11:00
}
```
### Full config example ( in webpack.conf.js )
```
module.exports = {
...
plugins: [
new WebpackAutoInject({
// specify the name of the tag in the outputed files eg
// bundle.js: [SHORT] Version: 0.13.36 ...
SHORT: 'CUSTOM',
SILENT: false,
PACKAGE_JSON_PATH: './package.json',
PACKAGE_JSON_INDENT: 4,
components: {
AutoIncreaseVersion: true,
InjectAsComment: true,
InjectByTag: true
},
componentsOptions: {
AutoIncreaseVersion: {
runInWatchMode: false // it will increase version with every single build!
},
InjectAsComment: {
tag: 'Version: {version} - {date}',
2018-10-28 04:59:02 +11:00
dateFormat: 'h:MM:ss TT', // change timezone: `UTC:h:MM:ss` or `GMT:h:MM:ss`
multiLineCommentType: false, // use `/** */` instead of `//` as comment block
},
InjectByTag: {
fileRegex: /\.+/,
// regexp to find [AIV] tag inside html, if you tag contains unallowed characters you can adjust the regex
// but also you can change [AIV] tag to anything you want
AIVTagRegexp: /(\[AIV])(([a-zA-Z{} ,:;!()_@\-"'\\\/])+)(\[\/AIV])/g,
dateFormat: 'h:MM:ss TT'
}
},
LOGS_TEXT: {
AIS_START: 'DEMO AIV started'
}
})
]
}
```
2016-10-20 19:32:26 +11:00
### Inject by tag example
```
<body>
<span>
[AIV]{version}[/AIV]
</span>
<span>
[AIV]{date}[/AIV]
</span>
<span>
[AIV]{version}_{date}[/AIV]
</span>
<span>
[AIV]V:{version} Date:{date}[/AIV]
</span>
<span>
[AIV]Version {version} , {date}[/AIV]
</span>
</body>
```
2017-04-13 07:47:11 +10:00
# Available options
2016-10-20 19:32:26 +11:00
2017-04-11 09:11:09 +10:00
### components.AutoIncreaseVersion
2016-10-20 19:32:26 +11:00
Auto increase package.json number. <br>
This option requires extra argument to be sent to webpack build. <br>
2016-10-21 18:32:35 +11:00
It happens before anything else to make sure that your new version is injected into your files.<br>
2017-04-11 09:11:09 +10:00
Arguments: --env.major --env.minor --env.patch<br><br>
2016-10-20 19:32:26 +11:00
Example for package.json run type, npm run start => ( 1.2.10 to 2.0.0 )
```json
"version" : "1.2.10",
"scripts": {
2017-04-11 09:11:09 +10:00
"start": "webpack --env.major"
2016-10-20 19:32:26 +11:00
}
```
To enable watch mode:
```
plugins: [
new WebpackAutoInject({
...
components: {
AutoIncreaseVersion: true,
...
},
componentsOptions: {
AutoIncreaseVersion: {
runInWatchMode: false // it will increase version with every single build!
}
}
})
]
```
2016-10-20 19:32:26 +11:00
Default: true
2017-04-11 09:11:09 +10:00
### components.InjectByTag
2016-10-21 18:32:35 +11:00
Inject version number into your file<br>
Version will replace the <{version}> tag.<br>
2016-10-20 19:32:26 +11:00
```html
2017-04-11 09:11:09 +10:00
<span>My awesome project | [AIV]{version}[/AIV]</span>
2016-10-20 19:32:26 +11:00
```
2016-10-21 18:32:35 +11:00
```js
2017-04-11 09:11:09 +10:00
var version = '[AIV]{version}[/AIV]';
2016-10-21 18:32:35 +11:00
```
2016-10-20 19:32:26 +11:00
Default: true
2017-04-11 09:11:09 +10:00
### components.InjectAsComment
This will inject your version as a comment into any css,js,html file.<br>
2017-04-13 08:40:22 +10:00
You can change what is injected into the file by changing componentsOptions.InjectAsComment.tag.
Currently only 2 tags are supported:
* {version}
* {date} ( current date )
Example:
``` javascript
...
plugins: [
...
new WebpackAutoInject({
PACKAGE_JSON_PATH: './package.json',
components: {
...
InjectAsComment: true
},
componentsOptions: {
...
InjectAsComment: {
tag: 'Build version: {version} - {date}', // default
2018-10-28 04:59:02 +11:00
dateFormat: 'dddd, mmmm dS, yyyy, h:MM:ss TT', // default
multiLineCommentType: false, // default
2017-04-13 08:40:22 +10:00
}
})
]
2018-10-28 04:59:02 +11:00
```
2017-04-11 09:11:09 +10:00
Default: true
2016-10-20 19:32:26 +11:00
2017-04-13 07:50:14 +10:00
# Output-examples
2017-04-13 07:47:11 +10:00
AIV can inject version number for all your bundle files (css,js,html).<br><br>
```js
// [AIV] Build version: 1.0.10
/******/ (function(modules) { // webpackBootstrap
/******/ // The module cache
/******/ var installedModules = {};
```
<br><br>
Example html:
```html
<!-- [AIV] Build version: 1.0.10 -->
<!DOCTYPE html>
<html lang="en">
```
2018-03-15 22:07:22 +11:00
# How to use with other webpack plugins
Webpack plugins order matters!
Always try to put WebpackAutoInject as a first webpack plugin.
## compression-webpack-plugin
```
plugins: [
new WebpackAutoInject(),
new CompressionPlugin(),
]
```
## uglifyjs-webpack-plugin
2017-04-13 07:47:11 +10:00
2018-03-15 22:07:22 +11:00
```
plugins: [
new WebpackAutoInject(),
new UglifyJsPlugin(),
]
```
## webpack.optimize.UglifyJsPlugin
If the order won't be enough, you can always add ignore to the uglifyJsPlugin
to prevent stripping out AIV comments eg:
```
new webpack.optimize.UglifyJsPlugin({
...
output: {
// prevent version info to be removed from bundle.js
comments: /\[AIV\]/,
},
...
});
```
2017-04-13 08:40:22 +10:00
# Change log
2018-10-28 05:06:03 +11:00
## [1.2.2] - 27/10/2018
- add PACKAGE_JSON_INDENT @trevyn
2018-10-28 05:02:16 +11:00
## [1.2.1] - 27/10/2018
- security updates
2018-10-28 04:59:02 +11:00
## [1.2.0] - 27/10/2018
- inject as comment will no more be a version behind with auto increase version
- inject as comment can now switched to multiline comment type eg /** */
- added support for npm log levels eg `npm start -s` will disable console logs
- unit tests added inside the `demo` folder, `npm run test`
2018-03-15 22:07:22 +11:00
## [1.1.0] - 15/03/2018
- webpack sync apply
- "name" has been removed as not used anyway, use SHORT instead
- eslint changes
- InjectByTag - AIVTagRegexp exposed in config to allow [AIV] tag modifications
- comma fix in InjectByTag regexp
- query has on filename has been fixed
## [1.0.0] - 25/08/2017
- Date format can now be specified for InjectAsComment
- Date format can now be specified for InjectByTag
- Webpack WATCH support added
- Root SILENT option added
- Minor fixes
## [0.5.14] - 12/04/2017
- Remove babel polyfills from webpack build as it was causing issues if babel was already used in project
2017-04-13 08:40:22 +10:00
## [0.5.13] - 12/04/2017
- Tag from InjectAsComment can now be configured by options ( componentsOptions.InjectAsComment.tag )
- Default tag template for InjectAsComment has change
## [0.5.12] - 12/04/2017
- Fix dependency missing issue
- Remove export as object with .default as a class