@bitfab/transform compatibility package

Compatibility package for the experimental build integrations that produce automatic first-party call spans beneath @bitfab.trace() and bitfab.withTrace() roots. Discovered calls configured with @bitfab.node() or bitfab.withNode() remain transform-eligible because the enclosing subtree trace still owns their spans.

The adapters now ship in @bitfab/sdk. New installations need only the SDK and should import adapters from @bitfab/sdk/transform/*. Existing @bitfab/transform imports remain supported during migration.

Install @bitfab/sdk, then add one bundled adapter where original server TypeScript or JavaScript is first compiled:

Next.js

import type { NextConfig } from "next"
import withBitfabTrace from "@bitfab/sdk/transform/next"

const nextConfig: NextConfig = {}
export default withBitfabTrace(nextConfig)

The wrapper instruments Node server modules in Turbopack and webpack builds. It does not instrument client or Edge bundles.

Instrumentation is scoped to the directory Next runs in, so sibling packages in a monorepo are left to add their own adapter. Pass cwd to widen or narrow that scope.

NestJS

Select Nest's webpack builder and point it at a normal custom webpack config:

{
  "compilerOptions": {
    "builder": "webpack",
    "webpackConfigPath": "webpack.config.cjs"
  }
}

const bitfabNestTrace = require("@bitfab/sdk/transform/nest").default

module.exports = bitfabNestTrace()

The wrapper preserves the webpack configuration generated by Nest and appends the shared Bitfab transform. Nest projects using the tsc or SWC builder still emit the rich trace() root, but need a corresponding compiler integration to discover child calls.

Explicit Bitfab spans

The transform does not instrument Bitfab's SDK implementation or the withSpan()/withTrace() call itself. It also recognizes inline and referenced functions passed to those wrappers and leaves their bodies alone, so an explicit withSpan() produces exactly one rich span instead of an additional automatic child. Named functions called from inside that explicit body remain eligible for automatic child spans.

The adapter rewrites eligible first-party functions because a build cannot reliably predict runtime calls through imports, dependency injection, callbacks, or virtual dispatch. Each rewritten function first checks the call-scoped runtime context. Outside trace() or withTrace(), it executes its original body directly without constructing span metadata, captured inputs, or an invocation closure. Destructured or defaulted arrow functions use a narrow function proxy so rich capture receives the original call arguments without rewriting parameter semantics; outside an active root, its apply trap invokes the original target immediately. Disabled or missing-key roots never request capture policy or activate the call-scoped context.

When server policy selects a function for rich capture, its input is the original argument array supplied at the call boundary. Object and array destructuring therefore preserve the complete argument rather than recording reconstructed bindings or a placeholder.

Unplugin build tools

All bundler exports are generated from the same Unplugin implementation and use the build tool's normal plugin array:

import bitfabTrace from "@bitfab/sdk/transform/vite"
import { defineConfig } from "vite"

export default defineConfig({ plugins: [bitfabTrace()] })

Use the corresponding subpath for Rollup, Rolldown, esbuild, Bun, webpack, Rspack, or Rsbuild. Vite-based React Router, Astro, Nuxt, and SvelteKit server modules use the Vite adapter. Functions embedded directly in .astro, .vue, or .svelte files are not yet instrumented.

Direct TypeScript execution

The registration hook instruments and transpiles ESM and CommonJS first-party modules inside the current working directory and enables their inline source maps:

node --import @bitfab/sdk/transform/register src/server.ts
node --import tsx --import @bitfab/sdk/transform/register src/server.ts

The Node loader resolves its injected runtime from the SDK available to the transform installation, including when shared packages do not depend on the SDK. To select a different application SDK installation, set BITFAB_SDK_RESOLVE_FROM to that application's package.json path:

BITFAB_SDK_RESOLVE_FROM=./packages/actor/package.json node --import @bitfab/sdk/transform/register packages/actor/src/server.ts

Run from the repository root to include shared packages in capture. This setting changes runtime resolution; the working directory still defines capture scope and relative function IDs. Both ESM and CommonJS use their respective SDK exports.

Projects that build with plain tsc should run the build through one of the bundler adapters or start Node with @bitfab/sdk/transform/register. Every adapter parses with Babel and needs Node 22.18 or later at build time.

Without an adapter, the root APIs remain valid and emit their normal rich root span. They simply cannot discover nested repository calls. The SDK prints one [bitfab] warning when a root finishes on Node in a build no adapter touched, naming the root and linking the documented installation steps. All adapters are experimental, and the generated function identity protocol may change.

Idle-path benchmark

Run pnpm bench:idle to compare an ordinary function with the common generated inactive in-body fast path. The benchmark alternates samples and reports median nanoseconds per call; it intentionally has no machine-dependent pass/fail threshold. It reports the destructured/defaulted-arrow proxy path separately from the common path so its additional inactive-call cost stays visible.