@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 also.

Usage

First prepare the drive

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)

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)

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)

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:

{
  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:

{
  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:

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

License

Apache-2.0