| 1 | # yarb
|
| 2 |
|
| 3 | [](https://travis-ci.org/mwiencek/yarb)
|
| 4 |
|
| 5 | yarb performs mostly the same task as [browserify](https://github.com/substack/node-browserify), and shares a lot of the same internals ([browser-pack](https://github.com/substack/browser-pack), [node-detective](https://github.com/substack/node-detective), [insert-module-globals](https://github.com/substack/insert-module-globals)).
|
| 6 |
|
| 7 | yarb is much less flexible than browserify, but better at defining dependencies between bundles. In browserify, sharing files between bundles tends to require a lot of manual `expose` and `external` settings on each file. A yarbundle’s `external` function only accepts other bundles as input, and the bundling process knows exactly which files are common to both.
|
| 8 |
|
| 9 | While yarb shares API similarities with browserify and is even compatible with browserify transforms, it currently does not handle the full array of core modules (only `events`, `fs`, `module`, `net`, `path`, `stream`, `util`), and lacks most of the settings and behaviors that browserify has.
|
| 10 |
|
| 11 | ## Notes
|
| 12 |
|
| 13 | Internally, yarb stores files as [vinyl](https://github.com/wearefractal/vinyl) objects, and even accepts these as input wherever a path is accepted. This allows passing in existing buffers/streams by just wrapping them in vinyl objects beforehand.
|
| 14 |
|
| 15 | The catch is that all vinyls must have a `path` property that is both unique to the bundle and absolute (though it doesn't have to exist on disk). Paths are how modules reference each other, after all.
|
| 16 |
|
| 17 | The `expose` method could theoretically support exposing a vinyl buffer/stream as an arbitrary ID, since those always take precedence over paths. That’d be a rare case, since the vast majority of things will be sourced from disk. Giving a fake but unique path where one doesn't exist will otherwise suffice.
|
| 18 |
|
| 19 | ## API
|
| 20 |
|
| 21 | ### var bundle = yarb([files[, options]])
|
| 22 |
|
| 23 | Returns a new bundle with `files` as entry points, i.e. modules executed when the bundle is loaded. `files` can be a single file or an array of files consisting of paths or vinyl objects.
|
| 24 |
|
| 25 | Current `options` are:
|
| 26 |
|
| 27 | Option | Purpose
|
| 28 | --------- | -------------
|
| 29 | `debug` | Enables source maps.
|
| 30 | `basedir` | Sets the starting point for resolving relative paths.
|
| 31 |
|
| 32 | ### bundle.add(files)
|
| 33 |
|
| 34 | Adds additional entry files to `bundle`. See above for accepted inputs for `files`.
|
| 35 |
|
| 36 | Returns `bundle`.
|
| 37 |
|
| 38 | ### bundle.require(files)
|
| 39 |
|
| 40 | Adds non-entry files to be included in `bundle`. Only necessary if you want to include files that aren’t referenced by any entry files, or are referenced dynamically (e.g. `require('foo' + bar)`);
|
| 41 |
|
| 42 | Returns `bundle`.
|
| 43 |
|
| 44 | ### bundle.external(externalBundle)
|
| 45 |
|
| 46 | Looks to `externalBundle` when resolving required paths/IDs, excluding all modules that exist in it from `bundle`. Obviously, `externalBundle` must be loaded on the page before anything that references it in `bundle` executes. Note that `externalBundle`’s externals will also be recursively checked, allowing a chain of dependencies to form.
|
| 47 |
|
| 48 | Returns `bundle`.
|
| 49 |
|
| 50 | ### bundle.expose(file, id)
|
| 51 |
|
| 52 | Calls `bundle.require` on `file` and aliases it as `id` for the current bundle and external bundles. `require(id)` will always takes precedence over normal path-resolution and always resolve to `file`.
|
| 53 |
|
| 54 | Returns `bundle`.
|
| 55 |
|
| 56 | ### bundle.transform(transform[, options])
|
| 57 |
|
| 58 | Adds browserify-compatible `transform` to execute on all file contents before being parsed for `require` calls.
|
| 59 |
|
| 60 | By default, transforms are not run on any code contained within a `node_modules/` directory relative to any of the bundle’s entry files. yarb supports a `global` flag in `options` which serves the same purpose as the one in browserify and forces the transform to run on all code.
|
| 61 |
|
| 62 | Returns `bundle`.
|
| 63 |
|
| 64 | ### bundle.bundle([callback])
|
| 65 |
|
| 66 | Bundles everything together for the browser.
|
| 67 |
|
| 68 | Returns a readable stream that can be piped to disk or elsewhere. If a node-style `callback` is given, it’ll execute on completion with the arguments `(error, buffer)`.
|
| 69 |
|
| 70 | ### bundle.has(path)
|
| 71 |
|
| 72 | Returns `true` if the bundle includes the file located at `path` in its output, otherwise `false`. Will only give accurate results after `bundle()` is called.
|
| 73 |
|
| 74 | ## License
|
| 75 |
|
| 76 | MIT
|