# Bundler API
URL: /runtime/api/bundler



Bundlers resolve imports, transpile code, and produce executable bundles for JS/TS kernel inputs.

## Types [#types]

**`EsbuildOptions`** — Public esbuild plugin options.

- **`extensions`** (`string[] | undefined`, optional)

**`BundlerPlugin`** — Registration object for a bundler plugin. Returned by the package-named alias such as `esbuild` from `@taucad/esbuild`, bound to the canonical `plugin` export.

- **`permissions`** (`RuntimePluginPermissions | undefined`, optional) — Declarative review metadata; runtime execution does not enforce these permissions.
- **`id`** (`Id`, required) — Unique identifier for this bundler
- **`extensions`** (`readonly string[]`, required) — File extensions this bundler handles
- **`options`** (`Record<string, unknown> | undefined`, optional) — Bundler-specific options

**`BundlerDefinition`** — Definition for a bundler module loaded via defineBundler(). Bundler modules are ES modules dynamically imported by the worker runtime. The bundler owns both bundling AND execution because the execution model is inherently tied to the bundler's output format. Detection (detectImports) and production (bundle) are separate operations: - detectImports: discovers what bare specifiers are used (no modules needed) - bundle: produces runnable code (modules must be registered first) This separation eliminates the chicken-and-egg problem: detection runs without modules registered, then the framework selects and initializes the kernel (which registers real modules), then bundle() produces code. Type parameters are inferred automatically: - Context from initialize() return type - Options from optionsSchema (when provided)

- **`name`** (`string`, required) — Human-readable bundler name, used in logs and error messages
- **`version`** (`string`, required) — Semantic version string for cache-key computation and diagnostics
- **`extensions`** (`string[]`, required) — File extensions this bundler handles (e.g., ['ts', 'js', 'tsx', 'jsx']).
- **`optionsSchema`** (`z.ZodType<Options, unknown, z.core.$ZodTypeInternals<Options, unknown>> | undefined`, optional) — Zod schema for validating and typing bundler options. Options type is inferred from this schema.
- **`initialize`** (`(options: Options, runtime: BundlerInitRuntime) => Promise<Context>`, required) — Initialize the bundler. Receives user-provided options plus framework runtime services.
- **`detectImports`** (`(input: BundleInput, runtime: BundlerRuntime, context: Context) => Promise<DetectImportsResult>`, required) — Detect which bare-specifier modules are imported transitively. Resolves relative imports normally but marks bare specifiers as external. Returns detected modules and project dependencies without producing runnable code. This is the primary mechanism for kernel selection -- no module stubs required.
- **`bundle`** (`(input: BundleInput, runtime: BundlerRuntime, context: Context) => Promise<BundleResult>`, required) — Produce runnable code with all registered modules resolved. Called AFTER kernel selection and initialization (modules are registered).
- **`execute`** (`(input: { code: string; }, runtime: BundlerRuntime, context: Context) => Promise<ExecuteResult>`, required) — Execute bundled code (tied to this bundler's output format).
- **`registerModule`** (`(input: { name: string; module: BuiltinModule; }, context: Context) => void`, required) — Register a builtin module for resolution during bundle().
- **`clearExecutionCache`** (`((code: string | undefined, context: Context) => void) | undefined`, optional) — Invalidate cached execution results after source changes.
- **`onDispose`** (`((context: Context) => Promise<void>) | undefined`, optional) — Clean up bundler resources (e.g., esbuild.stop()).

**`BundlerServices`** — Operation-scoped services supplied to bundler work.

- **`signal`** (`AbortSignal`, required) — Cancellation signal owned by the active runtime operation. Fresh for each operation; pass it to cancellable APIs and do not retain it.

**`KernelBundler`** — Bundler service exposed to kernels.

- **`bundle`** (`(entryPath: string) => Promise<BundleResult>`, required)
- **`resolveDependencies`** (`(entryPath: string) => Promise<GetDependenciesResult>`, required)
- **`registerModule`** (`(name: string, entry: BuiltinModule) => void`, required)

**`BundleResult`** — Result of bundling one entry and its transitive dependencies.

- **`code`** (`string`, required)
- **`sourceMap`** (`string | undefined`, optional)
- **`issues`** (`KernelIssue[]`, required)
- **`success`** (`boolean`, required)
- **`dependencies`** (`string[]`, required)
- **`unresolvedPaths`** (`string[]`, required)

## esbuild [#esbuild]

`esbuild()` installs the default esbuild-wasm bundler toolkit. Use `esbuildBundler(options)` only when configuring the role factory directly. Both handle `ts`, `js`, `tsx`, `jsx` by default.

## defineBundler [#definebundler]

`defineBundler` creates a `BundlerPluginFactory` from a configuration object. Required methods: `initialize`, `detectImports`, `bundle`, `execute`, `registerModule`. Optional: `clearExecutionCache`, `onDispose`.

Operation methods use `(input, runtime, context)`: a `BundleInput`, a `BundlerServices` carrying a fresh operation-scoped `AbortSignal`, and the persistent context returned by `initialize` (which receives a `BundlerInitServices`). `detectImports` returns a `DetectImportsResult`; `execute` returns an `ExecuteResult`. `entryPath` and returned dependency paths are canonical root-relative [runtime paths](/runtime/concepts/path-namespaces).

## Usage [#usage]

```typescript
import { createRuntimeClient } from '@taucad/runtime';
import { fromMemoryFs } from '@taucad/runtime/filesystem';
import { inProcessTransport } from '@taucad/runtime/transport/in-process';
import { defineRuntime } from '@taucad/runtime/worker';
import { replicad } from '@taucad/replicad';
import { esbuild } from '@taucad/esbuild';

const runtime = defineRuntime({
  plugins: [replicad(), esbuild()],
});

const client = createRuntimeClient({
  transport: inProcessTransport({ runtime, fileSystem: fromMemoryFs() }),
});
```

## Related [#related]

* [Configure the Bundler](/runtime/guides/bundler-configuration)
* [Cooperate with Cancellation](/runtime/guides/cooperate-with-cancellation)
* [Plugin System](/runtime/concepts/plugin-system)
* [Path Namespaces](/runtime/concepts/path-namespaces)