1# brfs 2 3fs.readFileSync() and fs.readFile() static asset browserify transform 4 5[![build status](https://secure.travis-ci.org/browserify/brfs.png)](http://travis-ci.org/browserify/brfs) 6 7This module is a plugin for [browserify](http://browserify.org) to parse the AST 8for `fs.readFileSync()` calls so that you can inline file contents into your 9bundles. 10 11Even though this module is intended for use with browserify, nothing about it is 12particularly specific to browserify so it should be generally useful in other 13projects. 14 15# example 16 17for a main.js: 18 19``` js 20var fs = require('fs'); 21var html = fs.readFileSync(__dirname + '/robot.html', 'utf8'); 22console.log(html); 23``` 24 25and a robot.html: 26 27``` html 28<b>beep boop</b> 29``` 30 31first `npm install brfs` into your project, then: 32 33## on the command-line 34 35``` 36$ browserify -t brfs example/main.js > bundle.js 37``` 38 39now in the bundle output file, 40 41``` js 42var html = fs.readFileSync(__dirname + '/robot.html', 'utf8'); 43``` 44 45turns into: 46 47``` js 48var html = "<b>beep boop</b>\n"; 49``` 50 51## or with the api 52 53``` js 54var browserify = require('browserify'); 55var fs = require('fs'); 56 57var b = browserify('example/main.js'); 58b.transform('brfs'); 59 60b.bundle().pipe(fs.createWriteStream('bundle.js')); 61``` 62 63## async 64 65You can also use `fs.readFile()`: 66 67``` js 68var fs = require('fs'); 69fs.readFile(__dirname + '/robot.html', 'utf8', function (err, html) { 70 console.log(html); 71}); 72``` 73 74When you run this code through brfs, it turns into: 75 76``` js 77var fs = require('fs'); 78process.nextTick(function () {(function (err, html) { 79 console.log(html); 80})(null,"<b>beep boop</b>\n")}); 81``` 82 83# methods 84 85brfs looks for: 86 87* `fs.readFileSync(pathExpr, enc=null)` 88* `fs.readFile(pathExpr, enc=null, cb)` 89* `fs.readdirSync(pathExpr)` 90* `fs.readdir(pathExpr, cb)` 91 92Inside of each `pathExpr`, you can use 93[statically analyzable](http://npmjs.org/package/static-eval) expressions and 94these variables and functions: 95 96* `__dirname` 97* `__filename` 98* `path` if you `var path = require('path')` first 99* `require.resolve()` 100 101Just like node, the default encoding is `null` and will give back a `Buffer`. 102If you want differently-encoded file contents for your inline content you can 103set `enc` to `'utf8'`, `'base64'`, or `'hex'`. 104 105In async mode when a callback `cb` is given, the contents of `pathExpr` are 106inlined into the source inside of a `process.nextTick()` call. 107 108When you use a `'file'`-event aware watcher such as 109[watchify](https://npmjs.org/package/watchify), the inlined assets will be 110updated automatically. 111 112If you want to use this plugin directly, not through browserify, the api 113follows. 114 115``` js 116var brfs = require('brfs') 117``` 118 119## var tr = brfs(file, opts) 120 121Return a through stream `tr` inlining `fs.readFileSync()` file contents 122in-place. 123 124Optionally, you can set which `opts.vars` will be used in the 125[static argument evaluation](https://npmjs.org/package/static-eval) 126in addition to `__dirname` and `__filename`. 127 128`opts.parserOpts` can be used to configure the parser brfs uses, 129[acorn](https://github.com/acornjs/acorn#main-parser). 130 131# events 132 133## tr.on('file', function (file) {}) 134 135For every file included with `fs.readFileSync()` or `fs.readFile()`, the `tr` 136instance emits a `'file'` event with the `file` path. 137 138# usage 139 140A tiny command-line program ships with this module to make debugging easier. 141 142``` 143usage: 144 145 brfs file 146 147 Inline `fs.readFileSync()` calls from `file`, printing the transformed file 148 contents to stdout. 149 150 brfs 151 brfs - 152 153 Inline `fs.readFileSync()` calls from stdin, printing the transformed file 154 contents to stdout. 155 156``` 157 158# install 159 160With [npm](https://npmjs.org) do: 161 162``` 163npm install brfs 164``` 165 166then use `-t brfs` with the browserify command or use `.transform('brfs')` from 167the browserify api. 168 169# gotchas 170 171Since `brfs` evaluates your source code *statically*, you can't use dynamic expressions that need to be evaluated at run time. For example: 172 173```js 174// WILL NOT WORK! 175var file = window.someFilePath; 176var str = require('fs').readFileSync(file, 'utf8'); 177``` 178 179Instead, you must use simpler expressions that can be resolved at build-time: 180 181```js 182var str = require('fs').readFileSync(__dirname + '/file.txt', 'utf8'); 183``` 184 185Another gotcha: `brfs` does not yet support ES module `import` statements. See [brfs-babel](https://github.com/Jam3/brfs-babel) for an experimental replacement that supports this syntax. 186 187# license 188 189MIT 190