bpb

browserify transform to safely replace process.browser with true by working on the Abstract Syntax Tree (AST)



introduction

The browserify/webpack implementation of process
has a special browser member set to true, which is not present in
the nodejs/iojs implementation of process.

``js
// on node
process.browser === undefined
// -> true

// on browser
process.browser === true
// -> true
`

This can be referenced in isomorphic code that
* adjusts it's behavior depending on which environment it's in
* is fully portable within the nodejs/iojs/browserify/webpack ecosystem, and
* is concise and Don't Repeat Yourself (DRY)

`js
// example #1
function animateElement(element) {
if (!process.browser){
throw new Error('animateElement function is for use client-side only!');
}
$(element).animate({/.../});
}

// example #2
function getCookie(name) {
return process.browser ? getCookieFromWindow(name) : getCookieFromRequest(req, name);
}
`

__This is where bpb (short for "browserify-processisfy.browserify") comes in.__

For optimized build-sizes and or security, use bpb in combination with unreachable-branch-transform (or a good minifier like UglifyJS) to strip out server-side-only code.

`js
// example #1 after bpb
function animateElement(element) {
if (!true){
throw new Error('animateElement function is for use client-side only!');
}
$(element).animate({/.../});
}

// example #1 after bpb + unreachable-branch-transform
function animateElement(element) {
$(element).animate({/.../});
}

// example #2 after bpb
function getCookie(name) {
return true ? getCookieFromWindow(name) : getCookieFromRequest(req, name);
}

// example #2 after bpb + unreachable-branch-transform
function getCookie(name) {
return getCookieFromWindow(name);
}
`

usage

*bpb can be used as a browserify transform, a
transform stream, or a synchronous function.*

$3

* ecmaVersion: Must be either 3, 5, or 6. Default is 5.

All options are passed directly to falafel which passes them directly to
acorn.

$3

`js
// as a browserify transform
var browserify = require('browserify');
var fs = require('fs');
browserify('input.js')
.transform('bpb', {/ options /})
.transform('unreachable-branch-transform')
.bundle()
.pipe(fs.createWriteStream('output.js'));

// as a transform stream
var fs = require('fs');
var bpb = require('bpb');
var unreachable = require('unreachable-branch-transform');
fs.createReadStream('input.js')
.pipe(bpb({/ options /}))
.pipe(unreachable())
.pipe(fs.createWriteStream('output.js'));

// as a synchronous function
var bpb = require('bpb');
var unreachable = require('unreachable-branch-transform');
unreachable.transform(bpb.sync('foo(process.browser ? 1 : 2);', {/ options /}))
// -> 'foo(1)'
``

changelog

$3

* emit errors rather than throw them

$3

* return passthrough for json files

$3

* added es6 support

$3

* added changelog to readme
* include readme in package files

$3

* safe implementation
* advanced tests

$3

* tests
* initial dumb implementation