You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
186 lines
4.2 KiB
186 lines
4.2 KiB
# brfs |
|
|
|
fs.readFileSync() and fs.readFile() static asset browserify transform |
|
|
|
[![build status](https://secure.travis-ci.org/substack/brfs.png)](http://travis-ci.org/substack/brfs) |
|
|
|
This module is a plugin for [browserify](http://browserify.org) to parse the AST |
|
for `fs.readFileSync()` calls so that you can inline file contents into your |
|
bundles. |
|
|
|
Even though this module is intended for use with browserify, nothing about it is |
|
particularly specific to browserify so it should be generally useful in other |
|
projects. |
|
|
|
# example |
|
|
|
for a main.js: |
|
|
|
``` js |
|
var fs = require('fs'); |
|
var html = fs.readFileSync(__dirname + '/robot.html', 'utf8'); |
|
console.log(html); |
|
``` |
|
|
|
and a robot.html: |
|
|
|
``` html |
|
<b>beep boop</b> |
|
``` |
|
|
|
first `npm install brfs` into your project, then: |
|
|
|
## on the command-line |
|
|
|
``` |
|
$ browserify -t brfs example/main.js > bundle.js |
|
``` |
|
|
|
now in the bundle output file, |
|
|
|
``` js |
|
var html = fs.readFileSync(__dirname + '/robot.html', 'utf8'); |
|
``` |
|
|
|
turns into: |
|
|
|
``` js |
|
var html = "<b>beep boop</b>\n"; |
|
``` |
|
|
|
## or with the api |
|
|
|
``` js |
|
var browserify = require('browserify'); |
|
var fs = require('fs'); |
|
|
|
var b = browserify('example/main.js'); |
|
b.transform('brfs'); |
|
|
|
b.bundle().pipe(fs.createWriteStream('bundle.js')); |
|
``` |
|
|
|
## async |
|
|
|
You can also use `fs.readFile()`: |
|
|
|
``` js |
|
var fs = require('fs'); |
|
fs.readFile(__dirname + '/robot.html', 'utf8', function (err, html) { |
|
console.log(html); |
|
}); |
|
``` |
|
|
|
When you run this code through brfs, it turns into: |
|
|
|
``` js |
|
var fs = require('fs'); |
|
process.nextTick(function () {(function (err, html) { |
|
console.log(html); |
|
})(null,"<b>beep boop</b>\n")}); |
|
``` |
|
|
|
# methods |
|
|
|
brfs looks for: |
|
|
|
* `fs.readFileSync(pathExpr, enc=null)` |
|
* `fs.readFile(pathExpr, enc=null, cb)` |
|
* `fs.readdirSync(pathExpr)` |
|
* `fs.readdir(pathExpr, cb)` |
|
|
|
Inside of each `pathExpr`, you can use |
|
[statically analyzable](http://npmjs.org/package/static-eval) expressions and |
|
these variables and functions: |
|
|
|
* `__dirname` |
|
* `__filename` |
|
* `path` if you `var path = require('path')` first |
|
* `require.resolve()` |
|
|
|
Just like node, the default encoding is `null` and will give back a `Buffer`. |
|
If you want differently-encoded file contents for your inline content you can |
|
set `enc` to `'utf8'`, `'base64'`, or `'hex'`. |
|
|
|
In async mode when a callback `cb` is given, the contents of `pathExpr` are |
|
inlined into the source inside of a `process.nextTick()` call. |
|
|
|
When you use a `'file'`-event aware watcher such as |
|
[watchify](https://npmjs.org/package/watchify), the inlined assets will be |
|
updated automatically. |
|
|
|
If you want to use this plugin directly, not through browserify, the api |
|
follows. |
|
|
|
``` js |
|
var brfs = require('brfs') |
|
``` |
|
|
|
## var tr = brfs(file, opts) |
|
|
|
Return a through stream `tr` inlining `fs.readFileSync()` file contents |
|
in-place. |
|
|
|
Optionally, you can set which `opts.vars` will be used in the |
|
[static argument evaluation](https://npmjs.org/package/static-eval) |
|
in addition to `__dirname` and `__filename`. |
|
|
|
# events |
|
|
|
## tr.on('file', function (file) {}) |
|
|
|
For every file included with `fs.readFileSync()` or `fs.readFile()`, the `tr` |
|
instance emits a `'file'` event with the `file` path. |
|
|
|
# usage |
|
|
|
A tiny command-line program ships with this module to make debugging easier. |
|
|
|
``` |
|
usage: |
|
|
|
brfs file |
|
|
|
Inline `fs.readFileSync()` calls from `file`, printing the transformed file |
|
contents to stdout. |
|
|
|
brfs |
|
brfs - |
|
|
|
Inline `fs.readFileSync()` calls from stdin, printing the transformed file |
|
contents to stdout. |
|
|
|
``` |
|
|
|
# install |
|
|
|
With [npm](https://npmjs.org) do: |
|
|
|
``` |
|
npm install brfs |
|
``` |
|
|
|
then use `-t brfs` with the browserify command or use `.transform('brfs')` from |
|
the browserify api. |
|
|
|
# gotchas |
|
|
|
Since `brfs` evaluates your source code *statically*, you can't use dynamic expressions that need to be evaluated at run time. For example: |
|
|
|
```js |
|
// WILL NOT WORK! |
|
var file = window.someFilePath; |
|
var str = require('fs').readFileSync(file, 'utf8'); |
|
``` |
|
|
|
Instead, you must use simpler expressions that can be resolved at build-time: |
|
|
|
```js |
|
var str = require('fs').readFileSync(__dirname + '/file.txt', 'utf8'); |
|
``` |
|
|
|
Another gotcha: `brfs` does not yet support ES2015 syntax like destructuring or `import` statements. See [brfs-babel](https://github.com/Jam3/brfs-babel) for an experimental replacement that supports this syntax. |
|
|
|
# license |
|
|
|
MIT
|
|
|