API Reference

Package: @tetherto/wdk-worklet-bundler

This reference covers @tetherto/wdk-worklet-bundler@1.0.0-beta.17. The package requires Node.js ^22.21.0 || >=24.9.0; see installation prerequisites.

Configuration Types

WdkBundleConfig

WdkBundleConfig is the public configuration shape for wdk.config.js.

import type { ConditionalSpecifier } from '@tetherto/wdk-worklet-bundler'

interface WdkBundleConfig {
  networks: Record<string, { package: string }>
  protocols?: Record<string, { package: string; [key: string]: unknown }>
  modules?: Record<string, {
    package: string
    factory?: string
    events?: string[]
  }>
  allowedMethods?: Record<string, {
    methods?: string[]
    protocols?: Record<string, Record<string, { methods?: string[] }>>
  }>
  allowedModuleMethods?: Record<string, { methods?: string[] }>
  preloadModules?: string[]
  transport?: 'hrpc' | 'jsonrpc'
  output?: {
    bundle?: string
    types?: string
    addons?: {
      ios?: string
      macos?: string
      android?: string
      linux?: string
      windows?: string
    }
    addonsYml?: string
  }
  options?: {
    minify?: boolean
    sourceMaps?: boolean
    targets?: string[]
    builtins?: ConditionalSpecifier[]
    linkAddons?: boolean
    swiftTarget?: string
    convertEsmToCjs?: boolean
    handleLeakCheck?: number | true
  }
}

allowedMethods is keyed by network. Its direct methods array restricts account calls, while protocols nests restrictions by protocol type and protocol name. allowedModuleMethods is keyed by generic-module name and applies to both HRPC and JSON-RPC. These inline helper shapes are present in the config declaration but are not named exports from the npm entrypoint.

Every omitted map, level, or methods field remains unrestricted. An explicit methods: [] denies every method on that exact surface. Both generated contexts receive allowedMethods and allowedModuleMethods.

Both transports support modules; use the installation example for the Pear runtime pairing and peer dependency. JSON-RPC defaults addon linking to true; HRPC defaults it to false. config.options.convertEsmToCjs defaults to false for both transports and must be enabled explicitly for targets whose Bare engine cannot load ESM.

options.handleLeakCheck is optional and applies only to generated HRPC entrypoints. Set true to use Pear Worklet's default 1000 ms interval, or a positive number to pass as tickIntervalMs. Omit it to disable diagnostics; false, zero, negative numbers, and strings fail loadConfig() validation. The interval controls repeated sampling after an immediate suspend snapshot, not a one-time delay.

Generation checks whether the installed Pear Worklet diagnostic subpath resolves, warning and skipping it if unavailable. The helper logs through console.warn until Bare idle or resume; it does not close handles. JSON-RPC generation accepts the option but does not emit diagnostic registration.

options.builtins accepts module specifiers and conditional specifiers such as { addon: 'bare-fs' } for addons already provided by the host. Host-provided addon versions must match the host build exactly; configuration validation does not verify that match.

ResolvedConfig

ResolvedConfig extends WdkBundleConfig with absolute filesystem paths produced by loadConfig().

interface ResolvedConfig extends WdkBundleConfig {
  configPath: string
  projectRoot: string
  resolvedOutput: {
    bundle: string
    types: string
    addons: {
      ios: string
      macos: string
      android: string
      linux: string
      windows: string
    }
    addonsYml: string
  }
}

Dependency Helpers

validateDependencies(modules, projectRoot)

Use this helper to confirm that the packages listed in wdk.config.js are already resolvable from the host project.

import { validateDependencies } from '@tetherto/wdk-worklet-bundler'

const result = validateDependencies(
  ['@tetherto/wdk-wallet-btc', '@tetherto/pear-wrk-wdk'],
  process.cwd()
)

ValidationResult contains:

• valid (boolean)
• installed (ModuleInfo[])
• missing (string[])

detectPackageManager(projectRoot)

Use this helper when you need the same package-manager detection logic that the CLI uses before install or uninstall flows.

import { detectPackageManager } from '@tetherto/wdk-worklet-bundler'

const packageManager = detectPackageManager(process.cwd())

generateInstallCommand(missing, packageManager?)

Build the install command string without mutating the project:

import { generateInstallCommand } from '@tetherto/wdk-worklet-bundler'

const command = generateInstallCommand(
  ['@tetherto/wdk-wallet-btc', '@tetherto/pear-wrk-wdk'],
  'npm'
)

installDependencies(missing, projectRoot, options?)

Run the install flow from code when you want the same dependency installation behavior as generate --install.

generateUninstallCommand(packages, packageManager?)

Build the uninstall command string without mutating the project.

uninstallDependencies(packages, projectRoot, options?)

Run the uninstall flow from code and receive a structured UninstallResult.

Bundle Generation

loadConfig(configPath?)

loadConfig() searches for wdk.config.js when no explicit path is supplied, validates the public config shape, and resolves the output paths relative to the config file directory.

import { loadConfig } from '@tetherto/wdk-worklet-bundler'

const config = await loadConfig()

generateBundle(config, options?)

Use generateBundle() when you want the same bundle workflow that powers the CLI generate command.

GenerateBundleOptions supports:

• dryRun
• verbose
• silent
• skipTypes
• skipGeneration: Reuse an existing generated entrypoint. Regenerate it after changing the entrypoint configuration.
• deferOptionalPeers? (boolean): When omitted or true, defer missing peers marked optional during packing. The peer scan checks root, nested, scoped, and symlinked package trees before treating an optional peer as missing. Set this option to false to require absent optional imports at build time.

deferOptionalPeers is a per-run API option. It is not a WdkBundleConfig field and cannot be set in wdk.config.js.

GenerateBundleResult contains:

• success
• bundlePath
• typesPath
• bundleSize: Written byte count on success, including any output wrapper.
• duration
• error?
• missingModule?
• pack?: Packing metadata containing id, hosts, files (file count), addons (addon hrefs), and esmToCjs ({ converted, packagesPatched } or null). Check for its presence before reading it; dry runs and some failure paths omit it.

Packing and conversion failures return success: false with error; an unresolved module may also set missingModule. Check success before using the output. Unlike packBundle(), these failures are returned rather than rejected.

typesPath can reflect a configured output.types path even though the declaration file is still written to ./.wdk/index.d.ts.

import { generateBundle, loadConfig } from '@tetherto/wdk-worklet-bundler'

const config = await loadConfig('./wdk.config.js')
const result = await generateBundle(config, { verbose: true })

generateSourceFiles(config, options?)

Use generateSourceFiles() when you want the generated entrypoint and host import without packing or conversion. The second options argument accepts only verbose. Pass the returned entry path to packBundle() for a custom build.

packBundle(options)

Pack an existing entrypoint into an in-memory bundle. Supply an absolute entry path and packOptions with the project-root file URL and target hosts. Enable convertEsmToCjs for a CommonJS-only target; it defaults to false. minify defaults to true and applies only during conversion.

Before enabling conversion, resolve same-basename .js/.mjs collisions.

For example, pack a source entrypoint at ./worklet/index.mjs and write a CommonJS-wrapped bundle:

import path from 'node:path'
import { pathToFileURL } from 'node:url'
import { packBundle, writeBundleFile } from '@tetherto/wdk-worklet-bundler'

const projectRoot = process.cwd()
const packed = await packBundle({
  entry: path.join(projectRoot, 'worklet/index.mjs'),
  packOptions: {
    base: pathToFileURL(projectRoot).href,
    hosts: ['ios-arm64'],
    linked: true
  },
  convertEsmToCjs: true
})

writeBundleFile(
  path.join(projectRoot, '.wdk-bundle/worklet.bundle.js'),
  packed.bundle
)

This packs and writes JavaScript; link any required native addons separately before deployment. PackBundleResult contains bundle, id, hosts, addons (addon hrefs), files (file count), and esmToCjs. Conversion statistics are { converted, packagesPatched } when enabled, or null otherwise. packBundle() does not write an output file and rejects on packing or conversion errors.

For TypeScript consumers, the package exports these supporting types:

import type {
  BarePackOptions,
  ConditionalSpecifier,
  EsmToCjsStats,
  PackBundleOptions,
  PackBundleResult
} from '@tetherto/wdk-worklet-bundler'

BarePackOptions accepts bare-pack options except resolve and aliases, plus defer?: string[]. Use builtins only for modules supplied by the host. See conversion configuration for target-engine requirements and limitations.

writeBundleFile(outputPath, bundle)

Serialize the in-memory bundle and write it synchronously, creating the parent directory if needed and overwriting an existing file. The returned Buffer contains the bytes written, including the selected wrapper. Filesystem errors throw.

wrapperForPath(outputPath)

Return the wrapper selected by the output filename:

The exported BundleWrapper type is 'cjs' | 'mjs' | 'json'; callers must also handle null.

generateEntryPoint(config, outputDir)

Use generateEntryPoint() when you need the generated HRPC Bare entrypoint written to a chosen output directory. This path includes configured generic modules, both method-allowlist maps, module lifecycle/event wiring, and the optional handleLeakCheck diagnostic.

The HRPC entrypoint scans require.cache for every loaded bare-http1 and bare-https module, deduplicates their globalAgent objects, and invokes each agent's suspend() or resume() method. It also invokes context.moduleRuntime.suspendAll() or resumeAll() when present. Each call is fire-and-forget; synchronous throws and rejected promises are logged without stopping the other lifecycle calls.

generateJsonRpcEntryPoint(config, outputDir)

Generate the framed JSON-RPC entrypoint used by native hosts. It includes wallet, protocol, and generic-module managers plus both method-allowlist maps. It generates the same fire-and-forget HTTP-agent and module-runtime lifecycle wiring as HRPC. options.handleLeakCheck is HRPC-only, so JSON-RPC does not emit diagnostic registration.

linkAddons(config, options?)

Link the native addons recorded in an existing packed bundle. Platforms come from config.options.targets: iOS, macOS, Android, Linux, or Windows according to the host prefixes. LinkAddonsOptions supports verbose, silent, and an optional in-memory bundle. When bundle is omitted, it reads config.resolvedOutput.bundle. The result contains success, duration, platforms, addons: LinkedAddon[], and optional error.

Each selected platform's addon output directory is cleared and rewritten. Keep it dedicated to generated files. For each platform, an addon package with no prebuild directory for any selected host is skipped; this does not confirm runtime support. Unsupported host families and missing required artifacts from addons with matching prebuilds produce a failed result; a project-root or ancestor output directory is rejected. A failure can follow partial output changes. generateBundle() also returns success: false if addon linking fails.

When iOS is selected, addon linking also calls generateAddonsYml() with config.options.swiftTarget or the default target name app.

readBundle(bundlePath)

Read a bare-pack artifact synchronously and return its parsed bare-bundle Bundle. Accepts raw bundles and bare-pack's default UTF-8 CommonJS, ESM, or JSON string wrappers. A missing file or invalid bundle throws. Custom non-UTF-8 wrappers are unsupported.

discoverLinkedAddons(bundle, projectRoot)

Inspect a parsed bundle packed with --linked and return native addon packages sorted by name. projectRoot is the directory where bare-pack ran. Each LinkedAddon has name, version, absolute package dir, and artefacts, whose entries have name and family (apple, elf, or windows). An unrecognized linked-artifact name or a missing package manifest in the bundle throws. Non-linked addon hrefs, including builtin: addons supplied by the host, are ignored. This function discovers requirements; it does not link or install addons.

generateAddonsYml(iosAddonsDir, swiftTarget, outputPath)

Generate the addons.yml dependency list expected by BareKit Swift from linked iOS XCFrameworks.

generateWalletModulesCode(config)

Use generateWalletModulesCode() when you only need the generated wallet-module section for inspection or custom generator flows.

CLI Commands

The published CLI exposes these commands through wdk-worklet-bundler:

For the end-to-end config workflow and transport defaults, see the Worklet Bundler configuration guide.

For older configs and custom build scripts, see addon platform migration and custom bundling migration.

Need Help?