bare-pack

bare-pack — Bundle packing for Bare.

npm i bare-pack

Usage

const pack = require('bare-pack')

async function readModule(url) {
  // Read `url` if it exists, otherwise `null`
}

async function* listPrefix(url) {
  // Yield URLs that have `url` as a prefix. The list may be empty.
}

const bundle = await pack(new URL('file:///directory/file.js'), readModule, listPrefix)

API

Functions

pack

pack(entry: URL, opts: PackOptions, readModule: ReadModuleCallback, listPrefix: ListPrefixCallback | null, writeFile: WriteFileCallback): Promise<Bundle>

Bundle the module graph rooted at url, which must be a WHATWG URL instance. readModule is called with a URL instance for every module to be read and must either return the module source, if it exists, or null. listPrefix is called with a URL instance of every prefix to be listed and must yield URL instances that have the specified URL as a prefix. If not provided, prefixes won't be bundled. writeFile is called for every addon or asset that should be offloaded rather than embedded; see the Offloading section of the README. When writeFile is provided, listPrefix must be passed positionally (or as null).

Parameters

Returns Promise<Bundle> — a promise that resolves to the packed bare-bundle Bundle, with all statically resolvable imports preresolved.

Types

PackOptions

interface PackOptions {
  concurrency?: number
  base?: URL | string
  offload?: boolean | { addons?: boolean; assets?: boolean }
  defaultType?: number
  aliases?: Record<string, AliasableExtension>
  resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
  builtinProtocol?: string
  builtins?: Builtins
  conditions?: Conditions
  extensions?: string[]
  host?: string
  hosts?: string[]
  linked?: boolean
  linkedProtocol?: string
  matchedConditions?: string[]
  resolutions?: ResolutionsMap
}

ReadModuleCallback

interface ReadModuleCallback {
}

ListPrefixCallback

interface ListPrefixCallback {
}

WriteFileCallback

interface WriteFileCallback {
}

CLI

bare-pack [flags] <entry>

Bundle the module graph rooted at <entry>. If --out is provided, the bundle will be written to the specified file. Otherwise, the bundle will be written to stdout.

Flags include:

--version|-v
--base <path>
--out|-o <path>
--builtins <path>
--imports <path>
--defer <specifier>
--linked
--offload
--offload-addons
--offload-assets
--format|-f
--encoding|-e
--host <host>
--help|-h

Host

By default, the bundle will be created for the host platform and architecture. To instead create a bundle for a different system, pass the --host flags.

bare-pack --host <platform>[-<arch>[-<environment>]] index.js

The --host flag may be specified multiple times to create a combined bundle for multiple systems.

[!TIP] Most often you'll use one of the possible values of Bare.Addon.host. Omitting the architecture and environment is also valid; --host ios will create a bundle for iOS with no architecture specific code, for example, whereas --host ios-arm64-simulator will create a bundle specifically for iOS ARM64 simulators.

Linking

If your runtime environment dynamically links native addons ahead of time using https://github.com/holepunchto/bare-link, pass the --linked flag to ensure that addons resolve to linked: specifiers instead of file: prebuilds. This will mostly always be necessary when targeting mobile as both iOS and Android require native code to be linked ahead of time rather than loaded at runtime from disk.

bare-pack --linked index.js

index.js

const addon = require.addon()

package.json

{
  "name": "addon",
  "version": "1.0.0",
  "addon": true
}

require.addon() will then resolve to linked:addon.1.0.0.framework/addon.1.0.0 on macOS and iOS, linked:libaddon.1.0.0.so on Linux and Android, and linked:addon-1.0.0.dll on Windows.

See example/addon for the full example.

Builtins

If your runtime environment includes builtin modules or statically embeds native addons, pass the --builtins flag and point it at a module exporting the list of builtins.

bare-pack --builtins builtins.json index.js

index.js

const addon = require('addon')

package.json

{
  "name": "builtin",
  "version": "1.0.0",
  "dependencies": {
    "addon": "file:../addon"
  }
}

To treat both the addon JavaScript module and native addon as being provided by the runtime environment, do:

builtins.json

["addon"]

To instead bundle the addon JavaScript module and only treat the native addon as being provided by the runtime environment, do:

builtins.json

[{ "addon": "addon" }]

See example/builtin for the full example.

Offloading

To keep addons and assets out of the bundle and write them to disk alongside --out instead, pass --offload (or --offload-addons / --offload-assets for a single kind). --out is required.

bare-pack --offload --out ./dist/index.bundle index.js

Each offloaded file is written at the directory of --out, mirroring its path relative to --base. The bundle's resolution for the file becomes /../<path-relative-to-base>, so when the bundle is later mounted (for example at ./dist/index.bundle/) the resolution points to the file's location next to the bundle. If --out happens to be inside --base, the file is not rewritten on disk.

Format

The bundle format to use will be inferred from the --out flag if specified and can also be set directly using the --format and --encoding flags.

bare-pack --format <bundle.cjs|bundle.mjs|bundle.json|bundle> --encoding <utf8|base64|ascii|hex|utf16le> index.js

The default encoding is utf8 for all text formats. Use base64 or hex if combining a text format with native addons or binary assets.

See also

• Builds on bare-bundle, bare-bundle-id, bare-fs, bare-module-traverse, and bare-path.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.