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