Skip to content

Load actor bundles without Bun re-transpiling them (DUR-138) - #465

Merged
oliviersm199 merged 2 commits into
mainfrom
olivier/DUR-138-load-actor-bundles-without-bun-retranspiling
Nov 10, 2026
Merged

oliviersm199 merged 2 commits into
mainfrom
olivier/DUR-138-load-actor-bundles-without-bun-retranspiling

Conversation

@oliviersm199

@oliviersm199 oliviersm199 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Fixes DUR-138

Problem

Actor hosts run on Bun, and Bun re-transpiles every JavaScript file it loads unless the file starts with // @bun. Our esbuild actor bundles don't start with it, so every load parses and reprints the whole bundle in memory before running it. That costs several times the bundle's size for a moment.

A Mastra chat actor (14.6 MB bundle) peaked about 206 MiB above an idle spare while loading. It was OOM-killed on 256 MiB spare pods.

Change

Actor bundles are now built with Bun's own bundler (Bun.build with target: "bun") instead of esbuild. esbuild targets Node and doesn't know about // @bun. Bun's bundler writes it automatically and loads CommonJS through import.meta.require, so the bundle needs no require shim.

Three Bun bundler behaviors needed handling:

  • Colliding class names. Bun renames a top-level class whose name collides with another module's. For example, an actor Chat that imports a dependency's Chat becomes Chat2. Bun's keepNames doesn't restore the name yet (oven-sh/bun#40503 is open). Actors are registered by class name, so the worker would reject the bundle with "actor entrypoint export Chat must have the same class name".
    • The generated entry module now resets each actor class's name to its export name. The compiler already requires the two to match in source.
    • Library classes and functions renamed this way still report the suffixed name.
  • CommonJS __dirname and __filename. Bun inlines the build machine's absolute paths for these. They now read the bundle's own location through define and a one-line banner. Bun's define treats import.meta.dirname as a string, so the values go through identifiers the banner sets.
  • build.resolve() in plugins. Bun doesn't implement it (oven-sh/bun#2771). The local-build plugin now resolves SDK imports with import-meta-resolve, as the Drizzle adapter plugin already did.

Smaller differences:

  • Bun strips the node: prefix from built-in imports, so node:crypto becomes crypto.
  • Bun doesn't lower syntax, so the old es2022 target no longer applies. The output only ever runs on Bun.
  • The generated entry module goes through files instead of esbuild's stdin.

@types/bun isn't added. Its types redefine Node's globals for the whole program, which broke the type-preservation tests and every typeof fetch parameter. actor-build.ts declares only the bundler API it uses. esbuild stays a dependency because build scripts and tests still use it.

Results

I used the demo AI SDK chat actor (ai plus @ai-sdk/* providers) and built it with the deployment compiler three ways. Each bundle was loaded through the host's worker supervisor on Bun 1.4.2 (Linux, Docker) with a cold transpiler cache. Figures are medians of 5 fresh processes, with peak memory measured above a trivial actor.

Build Bundle Extra peak memory while loading Ready in
main (esbuild, no // @bun) 2.9 MB 46 MiB 88 ms
esbuild with a // @bun banner (first commit) 2.9 MB 17 MiB 57 ms
Bun.build (this PR) 2.1 MB 10 MiB 43 ms

For the Mastra chat actor, an earlier run on Bun 1.4.4 measured a 206 MiB peak before and 85 MiB with the esbuild banner. In a separate comparison of the two bundlers on the same code, Bun's bundle peaked 12 MiB lower (80 versus 92 MiB) and was 12.4 MB instead of 14.5 MB.

Verification

  • New collision test. An actor class shares its name with a dependency's class, and the bundle loads through the host's artifact validator. Without the name reset it fails with "actor entrypoint export Counter must have the same class name".
  • CommonJS test (from the first commit). It checks that require, a relative require, __dirname and __filename behave as before and that the bundle starts with // @bun. I dropped its require.resolve("node:fs") check because Bun's bundler rewrites it to "fs".
  • Drizzle build test. Its expected import lines now have no banner import and use crypto.
  • Build errors still report the unresolved import with a code frame, file and line.
  • SDK suite. bun run --bun --cwd sdk test on Bun 1.4.4 gave 377 pass and 1 fail.
    • The failure is "importing actor definitions does not load remote transports or TypeScript tooling".
    • It also fails on main with Bun 1.4.4 and passes with the pinned 1.4.2.
  • Pinned Bun 1.4.2 (Linux, Docker). The build-artifact, Drizzle and package-root tests all pass (14 tests).
  • Formatting. Prettier passes on the changed files. format:check flags scripts/check-pr-ticket.mjs, scripts/release.mjs and tests/scripts/release-workflow.test.mjs, which this PR doesn't touch.
  • Not run locally: the Rust tests and the opt-in integration tests (cargo test -- --ignored).

Co-authored-by: Cursor <cursoragent@cursor.com>
@oliviersm199 oliviersm199 added the release:fix Include this PR under Fixes in release notes label Nov 10, 2026
Bun's bundler marks its output with // @Bun, so Bun loads actor bundles without re-transpiling them, and it
handles CommonJS require natively. Actor class names are restored in the generated entry because Bun renames
classes that collide with a dependency's names even with keepNames, and CommonJS __dirname and __filename
read the bundle's location instead of the build machine's paths.

Co-authored-by: Cursor <cursoragent@cursor.com>
@oliviersm199
oliviersm199 merged commit 92a1cb5 into main Nov 10, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release:fix Include this PR under Fixes in release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant