npm package: @lukks/boot-drive
Description: Run, bundle, or export apps and modules from a Hyperdrive or Localdrive
Author: Holepunch
Latest version: 1.0.1

# @lukks/boot-drive

Run, bundle, or export apps and modules from a Hyperdrive or Localdrive

```
npm i @lukks/boot-drive
```

There is a `boot` CLI available at [bootdrive-cli](https://github.com/lukks/bootdrive-cli) also.

## Usage

First prepare the drive

```js
const Boot = require('@lukks/boot-drive')
const Localdrive = require('localdrive')

const drive = new Localdrive('./app') // Or an existing folder app
await drive.put('/index.js', Buffer.from('module.exports = "Hello"'))

const boot = new Boot(drive)
await boot.warmup()
```

You can run it (executes the drive in the "sandboxed" Bootdrive runtime)

```js
const exported = boot.start()
console.log(exported) // Returns the `module.exports` from inside the drive
```

You can bundle it (single string, runtime included, prebuilds folder if any)

```js
const source = boot.stringify()
console.log(source) // Save it into a file or eval(source)
```

You can export it (minimal files, normal structure, no runtime)

```js
const out = new Localdrive('./out') // Always use a new empty drive
await boot.export(out)
```

## API

#### `const boot = new Boot(drive, [options])`

Creates a bootloader to run the drive.

Available `options`:

```js
{
  entrypoint: 'index.js', // Main file to be run at start
  cwd: '.', // Working directory for `prebuilds/`
  absolutePrebuilds: false, // If `true`, will use `cwd` for the stringified prebuilds path
  magic: false, // Inherit magic constants `__filename` and `__dirname`, also `module`
  cache: {}, // Used at runtime for `require.cache`, you can share it between boots
  dependencies: new Map(), // Used in `warmup()`, you can share linker deps between boots
  additionalBuiltins: [], // For adding modules to be imported by Node's native `require`
  builtinsMap: {}, // Mappings of core builtins, e.g. fs -> bare-fs
  sourceOverwrites: {}, // Key/Value object where you can map filenames to source code
  host: require.addon.host || process.platform + '-' + process.arch, // Prebuilds sub-dir
  platform: process.platform, // Legacy
  arch: process.arch // Legacy
}
```

Magic mostly disables isolation, and it handles hashbangs for CLI binaries.

When running a drive, there is `require.builtinRequire` provided by the JS runtime itself.

#### `await boot.warmup([entrypoint])`

Prepares the prebuilds and the dependencies of the drive.

If `entrypoint` is not set, then it will try `/package.json` `main` property.

If it fails to find an `entrypoint` then it will use `index.js` by default.

#### `const exports = boot.start([entrypoint])`

Executes the drive, and it returns the `module.exports` from inside the drive.

`absolutePrebuilds` is always forced to be `true` by default when using `boot.start()`.

#### `const source = boot.stringify([entrypoint], [options])`

Bundles the dependencies and source code of the drive into a single string.

Available `options`:

```js
{
  exports: false // Uses module.exports for the returned value of the isolated function
}
```

The `exports` option is not needed if you enable the `magic` constructor option.

Without `absolutePrebuilds` native modules has to always be in `./prebuilds/` related to the source file.

#### `await boot.export(drive, [options])`

Generate the minimal files required for a standalone run, with no Bootdrive runtime.

Exporting won't prune past files. Use a new drive and later `drive.mirror(dst, [opts])`.

Control atomicity with the `atomic` option in Localdrive, and mirror with `batch` option.

Available `options`:

```js
{
  entrypoint: null, // Same option as in the other methods above
  force: false // Include all files from all packages from entrypoints
}
```

## License

Apache-2.0