Browserify Banner Plug-in

Add a comment (and/or code) to the top of your Browserify bundle

Browserify Banner

Add a comment (and/or code) to the top of your Browserify bundle

Cross-Platform Compatibility Build Status

Coverage Status Dependencies

npm License

Features

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
 */

Installation

Install using npm:

npm install browserify-banner

Usage

Command Line

If used without any options, then it will automatically search for a file named “banner.txt”.

browserify -p browserify-banner

Or you can use Browserify’s sub-argument command-line syntax to specify a different file:

browserify -p [ browserify-banner --file src/license.txt ]

Or you can specify the banner template directly:

browserify -p [ browserify-banner --template "<%= pkg.name %> v<%= pkg.version %>" ]

Browserify API

Use the plugin programmatically like this:

var browserify = require('browserify');
var banner = require('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.

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! File an issue on GitHub and submit a pull request.

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 browserify-banner

  4. Run the tests
    npm test

License

browserify-banner is 100% free and open-source, under the MIT license. Use it however you want.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤

Travis CI SauceLabs Coveralls