@jsdevtools/browserify-banner

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:

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. 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 ❤