bare-pack
Bundle packing for Bare
v3.2.0bare-pack — Bundle packing for Bare.
npm i bare-packUpgrading from 2.x. Version 3.0.0 changed the arguments of pack(), what a bundle lists, and how the CLI resolves symlinks. Check these when you upgrade.
pack()takes a newresolveModulecallback betweenlistPrefixandwriteFile. A 2.x call that passeswriteFilein its old position, such aspack(entry, opts, readModule, null, writeFile), now passes it asresolveModule. YourwriteFileis then called with resolved URLs and no source, and offloaded files are left out of the bundle without being written. PassnullforresolveModuleinstead:pack(entry, opts, readModule, null, null, writeFile). Seepack.- Offloaded addons and assets stay listed in
bundle.addonsandbundle.assets, under their rewritten resolution, such as/../prebuilds/darwin-arm64/addon.bare. Version 2.x left them out of both lists. See Offloading. - The CLI follows symlinks. A package installed through a symlink is stored in the bundle under its real path, and its dependencies are looked up next to that path. If the real path is outside
--base, the module is stored under a/../key, which Bare reads from the file system next to the bundle, so the bundle works only where those real paths exist and fails withMODULE_NOT_FOUNDelsewhere. Set--baseto a directory that contains the real paths. See Symlinks.
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, resolveModule: ResolveModuleCallback | null, writeFile: WriteFileCallback): Promise<Bundle>Bundle the module graph rooted at entry, 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. resolveModule is called with the URL of each resolved module and returns the URL to use in its place; see Symlinks. writeFile is called for every addon or asset that should be offloaded rather than embedded; see Offloading. When writeFile is provided, listPrefix and resolveModule must be passed positionally (or as null).
opts can be left out, in which case the callbacks follow entry directly: pack(entry, readModule, listPrefix, resolveModule, writeFile).
Changed in v3.0.0: resolveModule was added before writeFile, which moved from the fifth argument to the sixth, or from the fourth to the fifth when opts is left out.
pack() calls readModule at most once for each URL and keeps the result, a null included, for the rest of the call. Before v2.2.3, readModule was called again each time the traversal asked for the same URL, which for a package.json meant once for every lookup of it. The listPrefix, resolveModule, and writeFile callbacks are not cached.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
entry | URL | — | The root of the module graph to bundle; must be a WHATWG URL instance (typically a file: URL). |
opts | PackOptions | — | Packing options, extending TraverseOptions from bare-module-traverse. Adds concurrency, base (the URL that offloaded file paths are made relative to), and offload (whether to write addons and/or assets to disk instead of embedding them). Can be left out. |
readModule | ReadModuleCallback | — | Called with a URL for every module in the graph; returns the module source as a Buffer or string, or null if it does not exist. Called at most once for each URL. |
listPrefix | ListPrefixCallback | null | — | Called with a URL for every prefix to list; yields the URLs that have it as a prefix. Pass null (or omit) to skip prefix bundling. |
resolveModule | ResolveModuleCallback | null | — | Called with the URL of each resolved module, addon, and asset; returns the URL to use in its place, such as its real path. Not called for entry. Defaults to the identity function. Added in v3.0.0. See Symlinks. |
writeFile | WriteFileCallback | — | Called for each addon or asset to offload rather than embed, receiving the file URL and its source. See Offloading. |
Returns Promise<Bundle> — a promise that resolves to the packed bare-bundle Bundle, with all statically resolvable imports preresolved.
Since v3.2.0, the bundle records the module type of each file it writes, as script, module, json, text, binary, addon or bundle, so that the loader doesn't have to infer it. A file that is also an asset leaves its type out, and its extension decides it instead.
Types
PackOptions
interface PackOptions {
concurrency?: number
base?: URL | string
offload?: boolean | { addons?: boolean; assets?: boolean }
defaultType?: number
importType?: number
artifacts?: boolean
aliases?: Record<string, AliasableExtension>
resolve?: (entry: Import, parentURL: URL, opts?: ResolveOptions) => Resolver
deferUnresolved?: boolean
mount?: URL | string
builtinProtocol?: string
builtins?: Builtins
conditions?: Conditions
defer?: string[]
deferredProtocol?: string
directories?: boolean
engines?: Engines
extensions?: string[]
imports?: ImportsMap
matchedConditions?: string[]
resolutions?: ResolutionsMap
host?: string
hosts?: string[]
linked?: boolean
linkedProtocol?: string
}concurrency, base, and offload belong to bare-pack. The other options come from the TraverseOptions of bare-module-traverse, which bare-pack depends on at ~2.7.0 since v2.2.5. Version 2.7 of bare-module-traverse added mount, and added the bare-module-resolve options defer, deferredProtocol, directories, engines, and imports to the type.
When the entry is itself a bundle, mount is the URL it is mounted at, and the addons and assets that it declares resolve against mount instead of the entry's URL. A bundle that the graph imports, such as require('./bar.bundle'), adds the addons and assets that it declares to bundle.addons and bundle.assets, resolved against its own URL. Both come from bare-module-traverse 2.7.1.
ReadModuleCallback
interface ReadModuleCallback {
(url: URL): Buffer | string | null | Promise<Buffer | string | null>
}Called with a URL for every module in the graph; returns the module source as a Buffer or string, or null if it does not exist. It may return a promise.
ListPrefixCallback
interface ListPrefixCallback {
(url: URL): Iterable<URL> | AsyncIterable<URL>
}Called with a URL for every prefix to list; yields the URLs that have it as a prefix. It may be an async generator.
ResolveModuleCallback
interface ResolveModuleCallback {
(url: URL): URL | Promise<URL>
}Called with the URL of each resolved module, addon, and asset; returns the URL to use in its place. The bundle stores the module under the returned URL, and the imports that resolved to url point to it. Added in v3.0.0. See Symlinks.
WriteFileCallback
interface WriteFileCallback {
(url: URL, source: Buffer | string): string | null | void | Promise<string | null | void>
}Called for each addon or asset to offload rather than embed, receiving the file URL and its source. It may return a promise. If it returns a string, that string replaces the file's resolution in the bundle's imports map and in bundle.addons or bundle.assets; otherwise, when base is set, the resolution defaults to '/../' + <path-relative-to-base>, which resolves to a sibling of the bundle. See Offloading.
bare-pack/fs
Functions
Callbacks for pack() that read from the file system. The CLI uses all three. On Bare, they use bare-fs and bare-url through the imports map of bare-pack. Types for these exports were added in v3.0.2.
const { pathToFileURL } = require('url')
const pack = require('bare-pack')
const { readModule, listPrefix, resolveModule } = require('bare-pack/fs')
const bundle = await pack(pathToFileURL('index.js'), readModule, listPrefix, resolveModule)readModule(url: URL): Promise<Buffer | null>
A readModule callback that reads url from the file system. Resolves to the file's contents, or null if it could not be read.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
url | URL | — | — |
Returns Promise<Buffer | null> — a promise that resolves to the module source, or null if it could not be read.
resolveModule(url: URL): Promise<URL>
A resolveModule callback that resolves a file: URL to its real path, following symlinks, and keeps a trailing slash. Other URLs, and URLs that cannot be resolved, such as a path that does not exist, are returned as they are. Added in v3.0.0.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
url | URL | — | — |
listPrefix(url: URL): AsyncGenerator<URL>
A listPrefix callback that yields url if it is a file, or every file nested under it if it is a directory.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
url | URL | — | — |
Aliases
To bundle source files with extensions that aren't natively recognized, use the aliases option (from bare-module-traverse) to map them to a supported extension. The aliased extension is used for module type detection, so readModule must return source compatible with that type. Aliased modules are stored in the bundle with the aliased extension, and resolutions to them are rewritten to match, so the example below stores file:///foo.js and file:///bar.js.
function readModule(url) {
if (url.href === 'file:///foo.ts') {
return "const bar = require('./bar.ts')"
}
if (url.href === 'file:///bar.ts') {
return 'module.exports = 42'
}
return null
}
const bundle = await pack(new URL('file:///foo.ts'), { aliases: { '.ts': '.js' } }, readModule)Offloading
To keep addons and assets out of the bundle, set offload to true (or { addons: true } / { assets: true } for a single kind) and provide a writeFile callback. Each offloaded file is passed to writeFile instead of being embedded. writeFile comes after listPrefix and resolveModule, so pass null for them if you don't need them.
function writeFile(url, source) {
// Persist `source` for `url`, e.g. to disk next to the bundle.
}
const bundle = await pack(
new URL('file:///app/foo.js'),
{ offload: true, base: new URL('file:///app/') },
readModule,
null,
null,
writeFile
)Offloaded files stay declared in bundle.addons and bundle.assets under their rewritten resolution, so the lists remain complete and loaders can tell which addons and assets the bundle needs. In the example above, an offloaded file:///app/prebuilds/darwin-arm64/addon.bare is listed as /../prebuilds/darwin-arm64/addon.bare. Changed in v3.0.0: version 2.x left offloaded files out of bundle.addons and bundle.assets.
URLs with the builtin:, linked:, or deferred: protocol are never offloaded.
Symlinks
Added in v3.0.0. Modules are resolved from the URLs they are read at, so a package installed through a symlink, as pnpm does, has its dependencies looked up next to the link rather than where the package actually lives. To follow symlinks like the module systems of Bare and Node do, pass a resolveModule callback, between listPrefix and writeFile, that maps each resolved URL to its real path. The resolveModule export of bare-pack/fs does this for file: URLs.
const { resolveModule } = require('bare-pack/fs')
const bundle = await pack(entry, opts, readModule, listPrefix, resolveModule)The bundle then stores each module under its real path, and the imports that went through the link resolve to that path. When base is set and a real path is outside it, the module is stored under a /../ key. Bare serves only the modules under the mount of a bundle and reads the rest from the file system, so such a bundle works only where the real paths exist next to it, as on the machine that packed it, and fails with MODULE_NOT_FOUND elsewhere; see Loading bundles. Set base, or --base for the CLI, to a directory that contains the real paths. Without resolveModule, a symlinked package whose dependencies sit next to its real path fails to pack with MODULE_NOT_FOUND.
WebAssembly addons
Added in v2.2.4. An addon package can ship a WebAssembly build as prebuilds/wasi-wasm32/<name>.wasm. bare-pack resolves these files through bare-module-traverse, which it depends on at ~2.7.0 since v2.2.5 (~2.6.0 in v2.2.4). The lookup, and the host and wasi import attributes, are described in WebAssembly addons on the bare-module-traverse page.
Without a host attribute, a WebAssembly build is bundled only when wasi-wasm32 is one of the hosts. Unlike Bare, bare-pack doesn't add that host on its own: the default resolver, an explicit hosts option, the presets, and the CLI leave it out unless you list it. The exception is resolve.bare from bare-module-traverse, which defaults hosts to [host, 'wasi-wasm32'] when hosts is not set ([host] for a freertos- host, as of bare-module-traverse v2.7.6), so pack() falls back to the WebAssembly build of a package that has no native build:
const traverse = require('bare-module-traverse')
const bundle = await pack(new URL('file:///app/foo.js'), { resolve: traverse.resolve.bare }, readModule)The .wasm file is read through readModule and embedded in the bundle like a native addon. Its URL is listed in bundle.addons, and offload passes it to writeFile with the other addons. The WebAssembly build is a fallback for a package that has no native build for any of the hosts. Native prebuilds are tried first, whatever the order of hosts. If at least one host has a native prebuild, only the native prebuilds are bundled, even when another host has none. Linked addons are tried before the .wasm file, so with linked set, a package with no native build resolves to a linked: specifier instead. resolve.bare and the CLI leave linked off unless you set it, but the default resolver passes the options to bare-addon-resolve as they are, where linked defaults to true. With the default resolver, set linked: false to bundle the .wasm file.
An import can ask for the WebAssembly build of its addons whatever hosts is, with require('addon', { with: { host: 'wasi-wasm32' } }) or import addon from 'addon' with { host: 'wasi-wasm32' }. The attribute applies to the addons of the imported module and of everything it imports. A wasi attribute names a module to bundle for the addon's WASI capabilities. pack() adds that module to the bundle and to the imports of the importing module, and resolves the module's own imports like the other imports of the importing module, so the addons it uses come from the bundle's hosts. A wasi attribute without host does not select the WebAssembly build: a package with a native build for the hosts gets its native addon. The bundle does not record which addon uses the module, because the wasi property that the traversal puts on the addon's dependency is not stored in the bundle. The addons of one package must load the same way throughout the graph, or pack() throws ADDON_HOST_INCOMPATIBLE or ADDON_WASI_INCOMPATIBLE.
Since v3.0.1, a module that the traversal reaches in several of these contexts, for example once with a wasi attribute and once without, is written to the bundle once, and an offloaded addon is passed to writeFile once.
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 <name>
--encoding|-e <name>
--host <host>
--preset <name>
--help|-hThe CLI reads modules with the callbacks of bare-pack/fs. Changed in v3.0.0: it also passes their resolveModule, so it follows symlinks. See Symlinks.
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.jsThe --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 ioswill create a bundle for iOS with no architecture specific code, for example, whereas--host ios-arm64-simulatorwill create a bundle specifically for iOS ARM64 simulators.
WebAssembly
Without a host attribute, WebAssembly prebuilds, found at prebuilds/wasi-wasm32/<name>.wasm, are only bundled when wasi-wasm32 is one of the hosts. The CLI always passes its own list of hosts, so it does not add wasi-wasm32 the way the resolve.bare default does. To bundle the WebAssembly build of an addon package that has no native build, pass --host wasi-wasm32 next to the native hosts:
bare-pack --host darwin-arm64 --host wasi-wasm32 index.jsNative prebuilds are used where they exist, whatever the order of the --host flags, and the .wasm file only for a package with no native build for any of the native hosts. With --host wasi-wasm32 alone, an addon package that has no .wasm build and is not a builtin fails with ADDON_NOT_FOUND. That includes the addons used by the module that a wasi attribute names. With --linked, a package with no native build resolves to a linked: specifier instead of its .wasm file. A --preset replaces the --host list, and no preset includes wasi-wasm32.
Imports with the host: 'wasi-wasm32' attribute always resolve to WebAssembly prebuilds, whatever the hosts are:
const { DatabaseSync } = require('bare-sqlite', { with: { host: 'wasi-wasm32', wasi: './wasi.js' } })See WebAssembly addons.
Presets
To bundle for a group of systems, pass --preset <name>. The options that a preset sets replace those from the flags, so --preset darwin --host wasi-wasm32 bundles for the darwin hosts only. An unknown name fails with Unknown preset '<name>'.
| Preset | Hosts | linked |
|---|---|---|
darwin | darwin-arm64, darwin-x64 | |
linux | linux-arm64, linux-x64 | |
win32 | win32-arm64, win32-x64 | |
desktop | The darwin, linux, and win32 hosts | |
ios | ios-arm64, ios-arm64-simulator, ios-x64-simulator | true |
android | android-arm, android-arm64, android-ia32, android-x64 | true |
mobile | The android and ios hosts | true |
watchos | watchos-arm64, watchos-arm64-32, watchos-arm64-simulator, watchos-x64-simulator | true |
Added in v3.1.0: the watchos preset, which mobile does not include. The presets are exported from bare-pack/preset. pack() applies a preset option the same way, although PackOptions does not declare it.
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.jsindex.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, iOS, and watchOS, 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.jsindex.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.jsEach 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 the directory of --out is --base itself, the files are not written, since they are already there. Changed in v3.0.0: the bundle's addons and assets list the offloaded files under these resolutions.
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| Format | Extensions | Description |
|---|---|---|
bundle.cjs | .bundle.js, .bundle.cjs | CommonJS wrapper for a .bundle |
bundle.mjs | .bundle.mjs | ES module wrapper for a .bundle |
bundle.json | .bundle.json | JSON wrapper for a .bundle |
bundle | .bundle, .* | Raw .bundle |
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, andbare-path.bare-module-traversewalks the module graph, and through itbare-addon-resolvefinds each package's addon, native or WebAssembly. - Bare modules — the full
bare-*catalog. - Bare runtime API — the runtime these modules extend.
Last updated on