# Bundler API
URL: /docs/api/bundler



Bundler API [#bundler-api]

Use the bundler API when configuring how JS/TS kernel inputs are bundled and executed. Bundlers resolve imports, transpile code, and produce executable bundles for the kernel runtime.

Types [#types]

<TypeTable
  type={{
  "name": "EsbuildOptions",
  "description": "Esbuild bundler options.",
  "entries": [
    {
      "name": "extensions",
      "description": "Override the default file extensions this bundler handles. Defaults to ['ts', 'js', 'tsx', 'jsx'].",
      "tags": [],
      "type": "string[] | undefined",
      "simplifiedType": "array",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "BundlerPlugin",
  "description": "Registration object for a bundler plugin. Returned by factory functions like `esbuild()`.",
  "entries": [
    {
      "name": "id",
      "description": "Unique identifier for this bundler",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "moduleUrl",
      "description": "URL of the bundler module",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "extensions",
      "description": "File extensions this bundler handles",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "options",
      "description": "Bundler-specific options",
      "tags": [],
      "type": "Record<string, unknown> | undefined",
      "simplifiedType": "Record<string, unknown>",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "BundlerDefinition",
  "description": "Definition for a bundler module loaded via defineBundler().\nBundler modules are ES modules dynamically imported by the worker runtime.\nThe bundler owns both bundling AND execution because the execution model\nis inherently tied to the bundler's output format.\n\nDetection (detectImports) and production (bundle) are separate operations:\n- detectImports: discovers what bare specifiers are used (no modules needed)\n- bundle: produces runnable code (modules must be registered first)\n\nThis separation eliminates the chicken-and-egg problem: detection runs\nwithout modules registered, then the framework selects and initializes\nthe kernel (which registers real modules), then bundle() produces code.\n\nType parameters are inferred automatically:\n- Context from initialize() return type\n- Options from optionsSchema (when provided)",
  "entries": [
    {
      "name": "name",
      "description": "Human-readable bundler name, used in logs and error messages",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "version",
      "description": "Semantic version string for cache-key computation and diagnostics",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "extensions",
      "description": "File extensions this bundler handles (e.g., ['ts', 'js', 'tsx', 'jsx']).",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "optionsSchema",
      "description": "Zod schema for validating and typing bundler options. Options type is inferred from this schema.",
      "tags": [],
      "type": "z.ZodType<Options, unknown, z.core.$ZodTypeInternals<Options, unknown>> | undefined",
      "simplifiedType": "object",
      "required": false,
      "deprecated": false
    },
    {
      "name": "initialize",
      "description": "Initialize the bundler. Receives framework init options plus user-provided options.",
      "tags": [],
      "type": "(initOptions: BundlerInitOptions, options: Options) => Promise<Context>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "detectImports",
      "description": "Detect which bare-specifier modules are imported transitively.\nResolves relative imports normally but marks bare specifiers as external.\nReturns detected modules and project dependencies without producing runnable code.\nThis is the primary mechanism for kernel selection -- no module stubs required.",
      "tags": [],
      "type": "(input: BundleInput, context: Context) => Promise<DetectImportsResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "bundle",
      "description": "Produce runnable code with all registered modules resolved.\nCalled AFTER kernel selection and initialization (modules are registered).",
      "tags": [],
      "type": "(input: BundleInput, context: Context) => Promise<BundleResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "execute",
      "description": "Execute bundled code (tied to this bundler's output format).",
      "tags": [],
      "type": "(code: string, context: Context) => Promise<ExecuteResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "registerModule",
      "description": "Register a builtin module for resolution during bundle().",
      "tags": [],
      "type": "(name: string, builtinModule: BuiltinModule, context: Context) => void",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "resolveDependencies",
      "description": "Optional fast-path dependency resolution without full bundling.\nFalls back to bundle().dependencies when not implemented.",
      "tags": [],
      "type": "((input: BundleInput, context: Context) => Promise<GetDependenciesResult>) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    },
    {
      "name": "cleanup",
      "description": "Clean up bundler resources (e.g., esbuild.stop()).",
      "tags": [],
      "type": "((context: Context) => Promise<void>) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "KernelBundler",
  "description": "Bundler service provided to kernel modules via KernelRuntime.\nWraps esbuild-wasm with virtual filesystem integration and CDN module resolution.\nCreated lazily on first access -- non-JS kernels incur zero cost.",
  "entries": [
    {
      "name": "bundle",
      "description": "Bundle a file and all its transitive dependencies.",
      "tags": [],
      "type": "(entryPath: string) => Promise<BundleResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "resolveDependencies",
      "description": "Resolve all transitive dependencies without generating output code.\nReturns both resolved dependencies and unresolved import paths.",
      "tags": [],
      "type": "(entryPath: string) => Promise<GetDependenciesResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "registerModule",
      "description": "Register a built-in module that will be served from memory during bundling.\nUsed by JS/TS kernels to register WASM-loaded libraries (replicad,",
      "tags": [
        {
          "name": "jscad",
          "text": "/modeling).\nMust be called before the first bundle() call."
        }
      ],
      "type": "(name: string, entry: BuiltinModule) => void",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "BundleResult",
  "description": "Result of bundling a file and its dependencies via esbuild.\nUsed by JS/TS kernels through runtime.bundler.",
  "entries": [
    {
      "name": "code",
      "description": "The bundled code as a string",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "sourceMap",
      "description": "Source map (if enabled)",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "Compilation issues (errors, warnings)",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "success",
      "description": "Whether bundling succeeded",
      "tags": [],
      "type": "boolean",
      "simplifiedType": "boolean",
      "required": true,
      "deprecated": false
    },
    {
      "name": "dependencies",
      "description": "Absolute paths of all project files that were resolved during bundling (transitive dependencies).",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "unresolvedPaths",
      "description": "Absolute paths of imports that could not be resolved during bundling — used for watch-set expansion.",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

esbuild [#esbuild]

`esbuild()` returns a `BundlerPlugin` that uses esbuild-wasm for bundling. Handles `ts`, `js`, `tsx`, `jsx` by default.

defineBundler [#definebundler]

`defineBundler` creates a bundler definition from a configuration object. Required methods: `initialize`, `detectImports`, `bundle`, `execute`, `registerModule`. Optional: `resolveDependencies`, `cleanup`.

Usage [#usage]

```typescript
import { createRuntimeClient, fromMemoryFS } from '@taucad/runtime';
import { replicad } from '@taucad/runtime/kernels';
import { esbuild } from '@taucad/runtime/bundler';

const client = createRuntimeClient({
  kernels: [replicad()],
  bundlers: [esbuild()],
  fileSystem: fromMemoryFS(),
});
```

Related [#related]

* [Configure the Bundler](../guides/bundler-configuration)
* [Plugin System](../concepts/plugin-system)