browserify-banner
v2.0.4
Published
Add a comment (and/or code) to the top of your Browserify bundle
Downloads
4,249
Maintainers
Readme
Browserify Banner
Add a comment (and/or code) to the top of your Browserify bundle
Features
- Customize your banner text using Lodash templates and Moment.js
- Inject any value from your package.json file into the banner
- Include JavaScript code to be run before your bundle is loaded
- Works with source maps (Browserify's
--debug
option)
Example
Here's an example banner template (can be in a file, passed via command-line, or set programmatically):
<%= _.startCase(pkg.name) %> v<%= pkg.version %> (<%= moment().format('MMMM Do YYYY') %>)
<%= pkg.description %>
<%= pkg.homepage %>
@author <%= pkg.author.name %> (<%= pkg.author.url %>)
@license <%= pkg.license %>
And here's what the banner would look like at the top of the Browserify bundle:
/*!
* My Library v1.23.456 (November 24th 2016)
* Lorem ipsum dolor sit amet, consectetur adipiscing malesuada ac elit.
*
* http://mycompany.com/my-library
*
* @author John Doe (http://linkedin.com/john-doe)
* @license MIT
*/
Related Projects
- globify - Run browserify and watchify with globs - even on Windows
- sourcemapify - Sourcemap plugin for Browserify
- simplifyify - A simplified Browserify and Watchify CLI
Installation
Install using npm:
npm install @jsdevtools/browserify-banner
Usage
Command Line
If used without any options, then it will automatically search for a file named "banner.txt".
browserify -p @jsdevtools/browserify-banner
Or you can use Browserify's sub-argument command-line syntax to specify a different file:
browserify -p [ @jsdevtools/browserify-banner --file src/license.txt ]
Or you can specify the banner template directly:
browserify -p [ @jsdevtools/browserify-banner --template "<%= pkg.name %> v<%= pkg.version %>" ]
Browserify API
Use the plugin programmatically like this:
var browserify = require('browserify');
var banner = require('@jsdevtools/browserify-banner');
browserify({debug: true})
.plugin(banner, {
// Custom object to use instead of the package.json file
pkg: {
name: 'My Library',
version: '1.23.456',
author: {
name: 'John Doe'
}
},
// Path to template file (defaults to "banner.txt")
file: 'path/to/my/banner/file.txt',
// Or just set the template directly (will be wrapped in a comment block)
template: '<%= pkg.name %> v<%= pkg.version %>\n' +
'<%= moment().format('MMMM Do YYYY') %>',
// Or set the banner directly (will NOT be wrapped in a comment block)
banner: '// This banner is NOT a template, so <%= this.doesnt.do.anything %>.\n' +
'// But I can inject custom code at the top of the bundle...\n' +
'window.myCustomVariable = Date.now();\n'
})
.bundle()
.pipe(fs.createWriteStream('bundle.js', 'utf8'));
Options
file
(string)
The path of a file to load the banner template from. The contents of this file are read and assigned to the template
option. By default, Browserify Banner will search for a file named "banner.txt", starting in the directory of your bundle's entry file, and crawling up the directory tree from there.
package
(string or object)
The path of the package.json file to apply to the banner template. Or you can set it to an object that will be applied as-is to the template. By default, Browserify Banner will use the first package.json file that is loaded by Browserify, which is usually the one associated with your bundle's entry file.
template
(string)
A Lodash template that will be used to create your bundle's banner. By default, this property is automatically set to the contents of the file
option, but if you set template
option, then it overrides the file
option.
This template can use <%= code.blocks %>
to inject variables into the banner. The template has access to the package.json file (e.g. pkg.name
, pkg.version
, etc). It also has access to all Lodash methods (e.g. _.filter()
, _.map()
, etc.) and the Moment.js library (e.g. moment.format()
, moment().startOf()
, etc).
Note: The template will automatically be wrapped in a comment block, unless it already starts with a comment. If your template contains JavaScript code that you want to be executed at the top of your bundle, then make sure that you start your code with a comment.
banner
(string)
If this option is set, then all other options are ignored and this banner is injected as-is at the top of your bundle. No modification is made to this text, so it's up to you to make sure that it contains valid comments and/or code.
Contributing
Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.
Building
To build the project locally on your computer:
Clone this repo
git clone https://github.com/JS-DevTools/browserify-banner.git
Install dependencies
npm install
Link the module to itself (so Browserify can find the plugin)
npm link
npm link @jsdevtools/browserify-banner
Run the tests
npm test
License
Browserify Banner is 100% free and open-source, under the MIT license. Use it however you want.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Big Thanks To
Thanks to these awesome companies for their support of Open Source developers ❤