diff options
Diffstat (limited to 'node_modules/envify/README.md')
| -rw-r--r-- | node_modules/envify/README.md | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/node_modules/envify/README.md b/node_modules/envify/README.md new file mode 100644 index 00000000..37f2c650 --- /dev/null +++ b/node_modules/envify/README.md @@ -0,0 +1,145 @@ +# envify [](http://travis-ci.org/hughsk/envify) [](http://github.com/hughsk/stability-badges) # + +Selectively replace Node-style environment variables with plain strings. +Available as a standalone CLI tool and a +[Browserify](http://browserify.org) v2 transform. + +Works best in combination with [uglifyify](http://github.com/hughsk/uglifyify). + +## Installation ## + +If you're using the module with Browserify: + +``` bash +npm install envify browserify +``` + +Or, for the CLI: + +``` bash +sudo npm install -g envify +``` + +## Usage ## + +envify will replace your environment variable checks with ordinary strings - +only the variables you use will be included, so you don't have to worry about, +say, `AWS_SECRET_KEY` leaking through either. Take this example script: + +``` javascript +if (process.env.NODE_ENV === "development") { + console.log('development only') +} +``` + +After running it through envify with `NODE_ENV` set to `production`, you'll +get this: + +``` javascript +if ("production" === "development") { + console.log('development only') +} +``` + +By running this through a good minifier (e.g. +[UglifyJS2](https://github.com/mishoo/UglifyJS)), the above code would be +stripped out completely. + +However, if you bundled the same script with `NODE_ENV` set to `development`: + +``` javascript +if ("development" === "development") { + console.log('development only') +} +``` + +The `if` statement will evaluate to `true`, so the code won't be removed. + +## CLI Usage ## + +With browserify: + +``` bash +browserify index.js -t envify > bundle.js +``` + +Or standalone: + +``` bash +envify index.js > bundle.js +``` + +You can also specify additional custom environment variables using +browserify's [subarg](http://github.com/substack/subarg) syntax, which is +available in versions 3.25.0 and above: + +``` bash +browserify index.js -t [ envify --NODE_ENV development ] > bundle.js +browserify index.js -t [ envify --NODE_ENV production ] > bundle.js +``` + +## Module Usage ## + +**require('envify')** + +Returns a transform stream that updates based on the Node process' +`process.env` object. + +**require('envify/custom')([environment])** + +If you want to stay away from your environment variables, you can supply +your own object to use in its place: + +``` javascript +var browserify = require('browserify') + , envify = require('envify/custom') + , fs = require('fs') + +var b = browserify('main.js') + , output = fs.createWriteStream('bundle.js') + +b.transform(envify({ + NODE_ENV: 'development' +})) +b.bundle().pipe(output) +``` + +## Purging `process.env` ## + +By default, environment variables that are not defined will be left untouched. +This is because in some cases, you might want to run an envify transform over +your source more than once, and removing these values would make that +impossible. + +However, if any references to `process.env` are remaining after transforming +your source with envify, browserify will automatically insert its shim for +Node's process object, which will increase the size of your bundle. This weighs +in at around 2KB, so if you're trying to be conservative with your bundle size +you can "purge" these remaining variables such that any missing ones are simply +replaced with undefined. + +To do so through the command-line, simply use the subarg syntax and include +`purge` after `envify`, e.g.: + +``` bash +browserify index.js -t [ envify purge --NODE_ENV development ] +``` + +Or if you're using the module API, you can pass `_: "purge"` into your +arguments like so: + +``` javascript +b.transform(envify({ + _: 'purge' + , NODE_ENV: 'development' +})) +``` + +## Contributors ## + +* [hughsk](http://github.com/hughsk) +* [benjamn](http://github.com/benjamn) +* [zag2art](http://github.com/zag2art) +* [bjoerge](http://github.com/bjoerge) +* [andreypopp](http://github.com/andreypopp) +* [jupl](http://github.com/jupl) |