# bare-union-bundle

[`bare-union-bundle`](https://github.com/holepunchto/bare-union-bundle) layers multiple [`bare-bundle`](/bare/reference/bare/modules) files into one **union bundle**, so modules resolve across a stack of bundles (for example, an app layer over a shared base). It's pure JavaScript, built on [`bare-module-traverse`](/bare/reference/bare/modules/bare-module-traverse).

```sh
npm i bare-union-bundle
```

## Usage [#usage]

```js
const UnionBundle = require('bare-union-bundle')

const b = UnionBundle.require('./0.bundle', './1.bundle', './2.bundle')

// load entrypoint.js from layer 1, unioning back to the project root
const mod = b.load(new URL('file:///root-of-project'), 'entrypoint.js', 1)
```

## API [#api]

#### `const b = new UnionBundle(bundles)` · `UnionBundle.require(...files)` [#const-b--new-unionbundlebundles--unionbundlerequirefiles]

Create a union from in-memory `bundles`, or load and union bundle files.

#### `const layer = await b.add(root, entrypoint[, opts])` [#const-layer--await-baddroot-entrypoint-opts]

Create a new layer bundle for `entrypoint` relative to `root`, returned as a [`bare-bundle`](/bare/reference/bare/modules) instance. Options:

```js
opts = {
  skipModules: true  // skip bundling dependencies under node_modules in root (boolean; default true)
}
```

Modules already referenced in the union's existing bundles are automatically skipped.

Serialize the layer with `layer.toBuffer()` and write it to a file to add it as another bundle in the union:

```js
const layer = await b.add(new URL('file:///root-of-project'), 'entrypoint.js')
await fs.writeFile('./3.bundle', layer.toBuffer())

// later, load across all four layers, including the new one
const union = UnionBundle.require('./0.bundle', './1.bundle', './2.bundle', './3.bundle')
const mod = union.load(new URL('file:///root-of-project'), 'entrypoint.js', 3)
```

#### `const bundle = b.checkout(index)` [#const-bundle--bcheckoutindex]

Extract a single layer as a standalone bundle.

#### `const mod = b.load(root, entrypoint, index[, opts])` [#const-mod--bloadroot-entrypoint-index-opts]

Load a module from layer `index`, resolving across the union back to `root`. Options:

```js
opts = {
  cache: require.cache,  // the module cache to load the entrypoint with (default require.cache)
  skipModules: true      // skip loading node_modules deps already in the cache (boolean; default true)
}
```

## Related modules [#related-modules]

Builds on [`bare-bundle`](/bare/reference/bare/modules), [`bare-module`](/bare/reference/bare/modules/bare-module), [`bare-module-traverse`](/bare/reference/bare/modules/bare-module-traverse), and [`bare-fs`](/bare/reference/bare/modules/bare-fs) (see [Bare modules](/bare/reference/bare/modules)).

## See also [#see-also]

* [`bare-pack`](/bare/reference/bare/modules)—produces the bundles a union layers together.
* [`bare-module-traverse`](/bare/reference/bare/modules/bare-module-traverse)—the traversal it uses to add layers.
* [Bare modules](/bare/reference/bare/modules)—the full `bare-*` catalog.