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.
187 lines
4.2 KiB
187 lines
4.2 KiB
5 years ago
|
# 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
|