File: readme.markdown

package info (click to toggle)
node-brfs 1.6.1-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 376 kB
  • sloc: makefile: 15; sh: 6
file content (189 lines) | stat: -rw-r--r-- 4,378 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
# brfs

fs.readFileSync() and fs.readFile() static asset browserify transform

[![build status](https://secure.travis-ci.org/browserify/brfs.png)](http://travis-ci.org/browserify/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`.

`opts.parserOpts` can be used to configure the parser brfs uses,
[acorn](https://github.com/acornjs/acorn#main-parser).

# 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 ES module `import` statements. See [brfs-babel](https://github.com/Jam3/brfs-babel) for an experimental replacement that supports this syntax.

# license

MIT