https://github.com/js-devtools/browserify-banner
Add a banner (comment and/or code) to the top of your Browserify bundle
https://github.com/js-devtools/browserify-banner
banner browserify browserify-plugin copyright header license
Last synced: about 2 months ago
JSON representation
Add a banner (comment and/or code) to the top of your Browserify bundle
- Host: GitHub
- URL: https://github.com/js-devtools/browserify-banner
- Owner: JS-DevTools
- License: mit
- Created: 2016-11-10T12:52:19.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2020-07-16T11:48:43.000Z (about 5 years ago)
- Last Synced: 2025-08-14T16:59:42.746Z (about 2 months ago)
- Topics: banner, browserify, browserify-plugin, copyright, header, license
- Language: JavaScript
- Homepage: https://jstools.dev/browserify-banner/
- Size: 451 KB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Browserify Banner
============================
#### Add a comment (and/or code) to the top of your Browserify bundle
[](https://github.com/JS-DevTools/browserify-banner/actions)
[](https://github.com/JS-DevTools/browserify-banner/actions)
[](https://coveralls.io/github/JS-DevTools/browserify-banner?branch=master)
[](https://david-dm.org/JS-DevTools/browserify-banner)
[](https://www.npmjs.com/package/@jsdevtools/browserify-banner)
[](LICENSE)
[](https://plant.treeware.earth/JS-DevTools/browserify-banner)
Features
--------------------------
* Customize your banner text using [Lodash templates](https://lodash.com/docs/4.16.6#template) and [Moment.js](http://momentjs.com/)
* 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:
```javascript
/*!
* 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](https://www.npmjs.com/package/globify) - Run browserify and watchify with globs - even on Windows
* [sourcemapify](https://www.npmjs.com/package/sourcemapify) - Sourcemap plugin for Browserify
* [simplifyify](https://www.npmjs.com/package/simplifyify) - A simplified Browserify and Watchify CLI
Installation
--------------------------
Install using [npm](https://docs.npmjs.com/getting-started/what-is-npm):
```bash
npm install @jsdevtools/browserify-banner
```
Usage
--------------------------
### Command Line
If used without any options, then it will automatically search for a file named "banner.txt".
```bash
browserify -p @jsdevtools/browserify-banner
```
Or you can use Browserify's sub-argument command-line syntax to specify a different file:
```bash
browserify -p [ @jsdevtools/browserify-banner --file src/license.txt ]
```
Or you can specify the banner template directly:
```bash
browserify -p [ @jsdevtools/browserify-banner --template "<%= pkg.name %> v<%= pkg.version %>" ]
```
### Browserify API
Use the plugin programmatically like this:
```javascript
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](https://lodash.com/docs/4.16.6#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](https://lodash.com/docs/4.16.6) (e.g. `_.filter()`, `_.map()`, etc.) and the [Moment.js](http://momentjs.com/) 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](https://github.com/JS-DevTools/browserify-banner/issues) on GitHub and [submit a pull request](https://github.com/JS-DevTools/browserify-banner/pulls).
#### Building
To build the project locally on your computer:
1. __Clone this repo__
`git clone https://github.com/JS-DevTools/browserify-banner.git`
2. __Install dependencies__
`npm install`
3. __Link the module to itself__ (so Browserify can find the plugin)
`npm link`
`npm link @jsdevtools/browserify-banner`
4. __Run the tests__
`npm test`
License
--------------------------
Browserify Banner is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/JS-DevTools/browserify-banner) 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 ❤
[](https://travis-ci.com)
[](https://saucelabs.com)
[](https://coveralls.io)