|
| 1 | +# envify [](http://travis-ci.org/hughsk/envify) [](http://github.com/hughsk/stability-badges) # |
| 2 | + |
| 3 | +Selectively replace Node-style environment variables with plain strings. |
| 4 | +Available as a standalone CLI tool and a |
| 5 | +[Browserify](http://browserify.org) v2 transform. |
| 6 | + |
| 7 | +Works best in combination with [uglifyify](http://github.com/hughsk/uglifyify). |
| 8 | + |
| 9 | +## Installation ## |
| 10 | + |
| 11 | +If you're using the module with Browserify: |
| 12 | + |
| 13 | +``` bash |
| 14 | +npm install envify browserify |
| 15 | +``` |
| 16 | + |
| 17 | +Or, for the CLI: |
| 18 | + |
| 19 | +``` bash |
| 20 | +sudo npm install -g envify |
| 21 | +``` |
| 22 | + |
| 23 | +## Usage ## |
| 24 | + |
| 25 | +envify will replace your environment variable checks with ordinary strings - |
| 26 | +only the variables you use will be included, so you don't have to worry about, |
| 27 | +say, `AWS_SECRET_KEY` leaking through either. Take this example script: |
| 28 | + |
| 29 | +``` javascript |
| 30 | +if (process.env.NODE_ENV === "development") { |
| 31 | + console.log('development only') |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +After running it through envify with `NODE_ENV` set to `production`, you'll |
| 36 | +get this: |
| 37 | + |
| 38 | +``` javascript |
| 39 | +if ("production" === "development") { |
| 40 | + console.log('development only') |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +By running this through a good minifier (e.g. |
| 45 | +[UglifyJS2](https://github.com/mishoo/UglifyJS)), the above code would be |
| 46 | +stripped out completely. |
| 47 | + |
| 48 | +However, if you bundled the same script with `NODE_ENV` set to `development`: |
| 49 | + |
| 50 | +``` javascript |
| 51 | +if ("development" === "development") { |
| 52 | + console.log('development only') |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +The `if` statement will evaluate to `true`, so the code won't be removed. |
| 57 | + |
| 58 | +## CLI Usage ## |
| 59 | + |
| 60 | +With browserify: |
| 61 | + |
| 62 | +``` bash |
| 63 | +browserify index.js -t envify > bundle.js |
| 64 | +``` |
| 65 | + |
| 66 | +Or standalone: |
| 67 | + |
| 68 | +``` bash |
| 69 | +envify index.js > bundle.js |
| 70 | +``` |
| 71 | + |
| 72 | +You can also specify additional custom environment variables using |
| 73 | +browserify's [subarg](http://github.com/substack/subarg) syntax, which is |
| 74 | +available in versions 3.25.0 and above: |
| 75 | + |
| 76 | +``` bash |
| 77 | +browserify index.js -t [ envify --NODE_ENV development ] > bundle.js |
| 78 | +browserify index.js -t [ envify --NODE_ENV production ] > bundle.js |
| 79 | +``` |
| 80 | + |
| 81 | +## Module Usage ## |
| 82 | + |
| 83 | +**require('envify')** |
| 84 | + |
| 85 | +Returns a transform stream that updates based on the Node process' |
| 86 | +`process.env` object. |
| 87 | + |
| 88 | +**require('envify/custom')([environment])** |
| 89 | + |
| 90 | +If you want to stay away from your environment variables, you can supply |
| 91 | +your own object to use in its place: |
| 92 | + |
| 93 | +``` javascript |
| 94 | +var browserify = require('browserify') |
| 95 | + , envify = require('envify/custom') |
| 96 | + , fs = require('fs') |
| 97 | + |
| 98 | +var b = browserify('main.js') |
| 99 | + , output = fs.createWriteStream('bundle.js') |
| 100 | + |
| 101 | +b.transform(envify({ |
| 102 | + NODE_ENV: 'development' |
| 103 | +})) |
| 104 | +b.bundle().pipe(output) |
| 105 | +``` |
| 106 | + |
| 107 | +## Purging `process.env` ## |
| 108 | + |
| 109 | +By default, environment variables that are not defined will be left untouched. |
| 110 | +This is because in some cases, you might want to run an envify transform over |
| 111 | +your source more than once, and removing these values would make that |
| 112 | +impossible. |
| 113 | + |
| 114 | +However, if any references to `process.env` are remaining after transforming |
| 115 | +your source with envify, browserify will automatically insert its shim for |
| 116 | +Node's process object, which will increase the size of your bundle. This weighs |
| 117 | +in at around 2KB, so if you're trying to be conservative with your bundle size |
| 118 | +you can "purge" these remaining variables such that any missing ones are simply |
| 119 | +replaced with undefined. |
| 120 | + |
| 121 | +To do so through the command-line, simply use the subarg syntax and include |
| 122 | +`purge` after `envify`, e.g.: |
| 123 | + |
| 124 | +``` bash |
| 125 | +browserify index.js -t [ envify purge --NODE_ENV development ] |
| 126 | +``` |
| 127 | + |
| 128 | +Or if you're using the module API, you can pass `_: "purge"` into your |
| 129 | +arguments like so: |
| 130 | + |
| 131 | +``` javascript |
| 132 | +b.transform(envify({ |
| 133 | + _: 'purge' |
| 134 | + , NODE_ENV: 'development' |
| 135 | +})) |
| 136 | +``` |
| 137 | + |
| 138 | +## Contributors ## |
| 139 | + |
| 140 | +* [hughsk](http://github.com/hughsk) |
| 141 | +* [benjamn](http://github.com/benjamn) |
| 142 | +* [zag2art](http://github.com/zag2art) |
| 143 | +* [bjoerge](http://github.com/bjoerge) |
| 144 | +* [andreypopp](http://github.com/andreypopp) |
| 145 | +* [jupl](http://github.com/jupl) |
0 commit comments