README update for browserify/webpack. add .git and demo to .npmignore

Author: lowe

.npmignore

@@ -1,6 +1,8 @@
+.git
 .gitignore
 bower.json
 data
 data-scripts
+demo
 test
 

README.md

@@ -53,7 +53,7 @@ To pull in updates and bug fixes:
 bower update zxcvbn
 ```
 
-## Node / npm / browserify
+## Node / npm
 
 zxcvbn works identically on the server.
 
@@ -64,8 +64,6 @@ $ node
 > zxcvbn('Tr0ub4dour&3');
 ```
 
-And should automatically work with browserify. The easiest browserify setup is to include zxcvbn in your main bundle. If script size is an issue, see the [performance](#perf) section below for tricks to reduce latency.
-
 ## RequireJS
 
 Add [`zxcvbn.js`](https://raw.githubusercontent.com/dropbox/zxcvbn/master/lib/zxcvbn.js) to your project (using bower, npm or direct download) and import as usual:
@@ -76,6 +74,29 @@ requirejs(["relpath/to/zxcvbn"], function (zxcvbn) {
 });
 ```
 
+## Browserify / Webpack
+
+If you're using `npm` and have `require('zxcvbn')` somewhere in your code, browserify and webpack should just work. But we recommend against bundling zxcvbn via tools like browserify and webpack, for three reasons:
+
+* Minified and gzipped, zxcvbn is still several hundred kilobytes. (Significantly grows bundle size.)
+* Most sites will only need zxcvbn on a few pages (registration, password reset).
+* Most sites won't need `zxcvbn()` immediately upon page load; since `zxcvbn()` is typically called in response to user events like filling in a password, there's ample time to fetch `zxcvbn.js` after initial html/css/js loads and renders.
+
+See the [performance](#perf) section below for tips on loading zxcvbn stand-alone.
+
+Tangentially, if you want to build your own standalone, consider tweaking the browserify pipeline used to generate `dist/zxcvbn.js`:
+
+``` shell
+browserify --debug --standalone zxcvbn -t coffeeify --extension='.coffee' -t uglifyify src/main.coffee | exorcist dist/zxcvbn.js.map >| dist/zxcvbn.js
+```
+
+* `--debug` adds an inline source map to the bundle. `exorcist` pulls it out into `dist/zxcvbn.js.map`.
+* `--standalone zxcvbn` exports a global `zxcvbn` when CommonJS/AMD isn't detected.
+* `-t coffeeify --extension='.coffee'` compiles `.coffee` to `.js` before bundling. This is convenient as it allows `.js` modules to import from `.coffee` modules and vice-versa. Instead of this transform, one could also compile everything to `.js` first (`npm run prepublish`) and point `browserify` to `lib` instead of `src`.
+* `-t uglifyify` minifies the bundle through UglifyJS, maintaining proper source mapping.
+
+Note that it is not advisable to "rebrowserify" or webpack `dist/zxcvbn.js`; make sure to bundle from `lib/*` (complied js), or, alternately `src/*` (coffee) using a transform/loader.
+
 ## Manual installation
 
 Download [zxcvbn.js](https://raw.githubusercontent.com/dropbox/zxcvbn/master/lib/zxcvbn.js).
@@ -172,7 +193,7 @@ Bug reports and pull requests welcome!
 git clone https://github.com/dropbox/zxcvbn.git
 ```
 
-zxcvbn is built with CoffeeScript, browserify, and uglify-js. CoffeeScript source lives in `src`, which gets compiled, bundled and minified into `lib/zxcvbn.js`.
+zxcvbn is built with CoffeeScript, browserify, and uglify-js. CoffeeScript source lives in `src`, which gets compiled, bundled and minified into `dist/zxcvbn.js`.
 
 ``` shell
 npm run build    # builds lib/zxcvbn.js
@@ -183,6 +204,8 @@ For debugging, both `build` and `watch` output an external source map `lib/zxcvb
 
 Two source files, `adjacency_graphs.coffee` and `frequency_lists.coffee`, are generated by python scripts in `data-scripts` that read raw data from the `data` directory.
 
+For node developers, in addition to `dist`, the zxcvbn `npm` module includes a `lib` directory (hidden from git) that includes one compiled `.js` and `.js.map` file for every `.coffee` in `src`. See `prepublish` in `package.json` to learn more.
+
 # Acknowledgments
 
 Dropbox for supporting open source!