npm package: @jsdevtools/browserify-banner
Description: Add a comment (and/or code) to the top of your Browserify bundle
Author: James Messinger
Latest version: 2.0.4

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

[![Cross-Platform Compatibility](https://jstools.dev/img/badges/os-badges.svg)](https://github.com/JS-DevTools/browserify-banner/actions)
[![Build Status](https://github.com/JS-DevTools/browserify-banner/workflows/CI-CD/badge.svg)](https://github.com/JS-DevTools/browserify-banner/actions)

[![Coverage Status](https://coveralls.io/repos/github/JS-DevTools/browserify-banner/badge.svg?branch=master)](https://coveralls.io/github/JS-DevTools/browserify-banner?branch=master)
[![Dependencies](https://david-dm.org/JS-DevTools/browserify-banner.svg)](https://david-dm.org/JS-DevTools/browserify-banner)

[![npm](https://img.shields.io/npm/v/@jsdevtools/browserify-banner.svg)](https://www.npmjs.com/package/@jsdevtools/browserify-banner)
[![License](https://img.shields.io/npm/l/@jsdevtools/browserify-banner.svg)](LICENSE)
[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](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__<br>
`git clone https://github.com/JS-DevTools/browserify-banner.git`

2. __Install dependencies__<br>
`npm install`

3. __Link the module to itself__ (so Browserify can find the plugin)<br>
`npm link`<br>
`npm link @jsdevtools/browserify-banner`

4. __Run the tests__<br>
`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 ❤

[![Travis CI](https://jstools.dev/img/badges/travis-ci.svg)](https://travis-ci.com)
[![SauceLabs](https://jstools.dev/img/badges/sauce-labs.svg)](https://saucelabs.com)
[![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io)