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[]
  }>
  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
  }
}

modules is generated only for HRPC through beta.7. JSON-RPC entry generation ignores that map. JSON-RPC otherwise defaults addon linking and ESM-to-CJS conversion to true; HRPC defaults both to false.

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
• deferOptionalPeers? (boolean): When omitted or true, pass missing peers marked optional through bare-pack --defer. Beta.7 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.7, 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.

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

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.

generateJsonRpcEntryPoint(config, outputDir)

Generate the framed JSON-RPC entrypoint used by native hosts. Through beta.7 this path includes wallet and protocol managers but not generic modules.

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.

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?