API Reference

Package: @tetherto/wdk-worklet-bundler

Configuration Types

WdkBundleConfig

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

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
    }
    addonsYml?: string
  }
  options?: {
    minify?: boolean
    sourceMaps?: boolean
    targets?: string[]
    linkAddons?: boolean
    platforms?: Array<'ios' | 'macos' | 'android'>
    swiftTarget?: string
    convertEsmToCjs?: boolean
  }
}

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 HRPC only. These inline helper shapes are present in the config declaration but are not named exports from the beta.10 npm entrypoint.

Every omitted map, level, or methods field remains unrestricted. An explicit methods: [] denies every method on that exact surface. Generated HRPC contexts receive both maps; generated JSON-RPC contexts receive only allowedMethods.

modules is generated only for HRPC through beta.10. JSON-RPC entry generation ignores that map. JSON-RPC defaults addon linking to true; HRPC defaults it to false. options.convertEsmToCjs defaults to false for both transports and must be enabled explicitly for targets whose Bare engine cannot load ESM.

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
    }
    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. If config.options.convertEsmToCjs changed, regenerate the entrypoint first so its .mjs loader behavior matches the bundle conversion.
• deferOptionalPeers? (boolean): When omitted or true, pass missing peers marked optional through bare-pack --defer. Beta.10 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
• duration
• error?
• missingModule?

In beta.10, 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 without the final bare-pack step.

options.convertEsmToCjs: true adds the runtime .mjs CommonJS-loader patch to that entrypoint, but this function does not pack or convert a bundle. If you run bare-pack yourself, call convertBundleEsmToCjs() on its output and keep the same conversion setting used to generate the entrypoint.

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, and module lifecycle/event wiring.

Starting in beta.3, the generated entrypoint suspends and resumes both the bare-http1 and bare-https global agents when the Bare runtime emits suspend and resume. Beta.10 also logs the generated worklet's Bare suspend, resume, and idle events. When options.convertEsmToCjs is enabled, beta.10 also emits the matching runtime .mjs-as-CommonJS loader patch.

generateJsonRpcEntryPoint(config, outputDir)

Generate the framed JSON-RPC entrypoint used by native hosts. Through beta.10 this path includes wallet and protocol managers plus allowedMethods, but not generic modules or allowedModuleMethods. When options.convertEsmToCjs is enabled, it emits the same .mjs loader patch as the HRPC generator.

linkAddons(config, options?)

Link required Bare addons for iOS, macOS, Android, or a selected subset. LinkAddonsOptions supports platforms, verbose, and silent. The result contains success, duration, platforms, and optional error.

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

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.

convertBundleEsmToCjs(bundlePath, options?)

Rewrites a bare-pack bundle in place for a CommonJS-only engine:

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

convertBundleEsmToCjs('./.wdk-bundle/wdk-worklet.bundle.js', {
  minify: true,
  verbose: false
})

The beta.10 converter accepts raw .bundle data and the default UTF-8 CommonJS, ESM, or JSON string wrappers produced by bare-pack. Wrappers created with a non-UTF-8 --encoding, such as Base64, are not supported. The converter transforms .js, .mjs, and .cjs files, lowers dynamic imports, removes "type": "module" from bundled package manifests, recomputes offsets with bare-bundle, restores the original wrapper, and calls validateBundle() before returning. It throws if any source transformation or final validation fails.

This helper rewrites only the packed bundle. For .mjs files to load as CommonJS at runtime, generate the HRPC or JSON-RPC entrypoint with options.convertEsmToCjs: true before packing, or provide equivalent loader behavior yourself. Do not convert a bundle while reusing an entrypoint generated with conversion disabled.

The inline options shape has minify?: boolean and verbose?: boolean. ConvertOptions appears in the generated declaration as the parameter shape but is not a named export from the beta.10 package entrypoint.

validateBundle(bundlePath)

Validates a converted bundle without changing it:

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

validateBundle('./.wdk-bundle/wdk-worklet.bundle.js')

The function checks wrapper and header parsing, file offsets and lengths, the entrypoint, CommonJS syntax, remaining dynamic imports, and package manifests that still declare ESM. It returns void on success and throws an aggregated error on failure. Because the syntax checks expect CommonJS, use it for converted artifacts rather than an intentionally ESM bundle.

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.

Need Help?