Uh oh!
There was an error while loading. Please reload this page.
[rollup] Externalize optional @opentelemetry/api peer (only when absent) so framework builds don't fail - #1947
Conversation
`@opentelemetry/api` is an optional peer dependency loaded via a
try/catch'd `await import('@opentelemetry/api')`. Bundlers that
statically follow `import('…')` strings reject it as unresolvable when
the consumer hasn't installed it — SvelteKit's Rollup pipeline turns
this into a fatal build error:
[vite]: Rollup failed to resolve import "@opentelemetry/api" from
"src/routes/.well-known/workflow/v1/flow/__step_registrations.js"
Construct the specifier at runtime so the static analyzer can't resolve
it. The `globalThis`-cached symbol pattern used by `get-world-lazy.ts`
works for the same reason. Runtime semantics are unchanged: present →
loaded, absent → caught and tracing disabled.
Other build systems (Next.js, Nitro, Astro, Hono, Nuxt) tolerate the
unresolvable specifier today, so they were unaffected — but the same
pattern fails for any bundler that treats unresolved static specifiers
as fatal, and depending on transitive resolution to provide the peer
is brittle.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: ec311ea The changes in this PR will be included in the next version bump. This PR includes changesets to release 16 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
📊 Workflow Benchmarkscommit Backend:
📜 Previous results (3)82b4b0cThu, 09 Jul 2026 23:26:29 GMT · run logs
9a30ea5Thu, 09 Jul 2026 22:13:10 GMT · run logs
22045b9Thu, 09 Jul 2026 19:55:20 GMT · run logs
Avg deltas compare against the most recent benchmark run on Metrics — TTFS: time to first step body execution · STSO: step-to-step overhead (gap between consecutive step bodies) · WO: workflow overhead (time outside step bodies, client start → last step body exit) · SL: stream latency (first chunk write → visible to the reader) Scenarios — stream: one step that streams chunks back to the client; no hooks, so the run stays in turbo mode · hook + stream: registers a hook before the same streaming step, which exits turbo mode · 1020 steps: 1020 trivial sequential steps; STSO is measured between consecutive steps in the given step ranges 🟢/🔴 mark percentiles within/above target. Targets (p75/p90/p99, ms) — TTFS 200/300/600 · SL 50/60/125 · STSO (1-20) 20/30/60 · STSO (101-120) 30/45/90 · STSO (1001-1020) 40/60/120 TTFS/WO compare client vs deployment clocks and SL compares the step runner’s clock vs the client’s (NTP-synced in CI). WO ends at the last step body exit, the closest observable proxy for the final step-completion request. |
| const specifier = ['@opentelemetry', 'api'].join('/'); | ||
| try { | ||
| return await import('@opentelemetry/api'); | ||
| return (await import(specifier)) as typeof api; |
There was a problem hiding this comment.
Should we mark this as external instead?
There was a problem hiding this comment.
AI Review: Note
Correction to my earlier point — we do control bundler config for the framework integrations we ship (packages/sveltekit, packages/next, packages/nitro, packages/nuxt, packages/astro, etc.), and the Next integration already manipulates serverExternalPackages / webpack externals. So we could plausibly add @opentelemetry/api to a per-framework externals list and avoid touching the source.
Why I still think opacifying the specifier is the right call:
- Coverage. The source-level fix works for every consumer — including users who don't go through our integrations (direct
@workflow/coreuse, custom Vite/Rollup setups, the workbench builders app's downstream consumers, future frameworks we haven't written an integration for yet). The externalize-per-integration path requires us to maintain a parallel allowlist in 6+ packages and remember to update it whenever the optional-peer surface grows. - Consistency.
packages/core/src/runtime/get-world-lazy.ts:54already uses the runtime-built-specifier trick for the same class of problem (./world.jsgetting traced into bundles where the sibling doesn't exist). Keeping the two consistent feels right. - Defense in depth. Even if we externalize in our SvelteKit plugin, a user with their own
vite.config.tsoverriding our config could re-break it. The one-line source fix can't be undone by consumer config.
Happy to additionally externalize in the integrations if you'd prefer belt-and-suspenders, but the source-level fix is what closes the actual reproduction in the PR description.
karthikscale3
left a comment
There was a problem hiding this comment.
[P1] Preserve OTel for the example workflow-server e2e lane
Making the @opentelemetry/api import opaque means bundlers/file tracers no longer include that package. That is intentional for apps without OTel, but it can silently disable SDK/world spans in OTel-enabled apps that only install @vercel/otel. workbench/example is in the Vercel e2e matrix, imports @vercel/otel, but does not directly depend on @opentelemetry/api; from that app, import(["@opentelemetry", "api"].join("/")) still fails with ERR_MODULE_NOT_FOUND even after loading @vercel/otel. Since these helpers catch the failure and turn tracing off, this would break the existing workflow/workflow-server OTel interaction for the example e2e deployment. Please add @opentelemetry/api directly to workbench/example/package.json and ideally document that @vercel/otel alone is not enough for Workflow SDK spans after this change.
…opaque import
The opaque runtime-built specifier fixed the SvelteKit/Rollup build failure but
silently disabled tracing on esbuild self-contained targets (the CLI's
vercel-build-output-api build, Nitro, Astro): those ship a bundle with no
node_modules, so an opaque import can't be inlined and resolves to nothing at
runtime — including the `example` e2e deployment.
Revert core/world-local/world-vercel to a static `import('@opentelemetry/api')`
(esbuild inlines it, nft traces it → tracing works when the peer is present),
and mark `@opentelemetry/api` external in the shared @workflow/rollup transform
plugin so Rollup/Vite framework builds (SvelteKit, Nitro, Nuxt, Astro, Vite)
stay green when the optional peer isn't installed. Verified: the peer-absent
build fails on Vite 6/7 without the external and passes with it.
Also pin @opentelemetry/api directly in workbench/example (aligning it with the
other workbenches) and add a @workflow/rollup regression test.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>VaguelySerious
commented
Jul 9, 2026
(AI) Addressed the P1, but changed the approach after digging into the failure mode you flagged. You were right that the opaque import breaks OTel — and it's actually worse than "only So instead of making the import opaque, this now:
Also did what you asked directly: pinned |
Unconditionally externalizing broke the Nitro-based e2e apps (express, fastify, hono, nitro, tanstack): Nitro's `.output/server` is a self-contained bundle with no node_modules, so marking the peer external stranded the runtime import and crashed the server at startup with ERR_MODULE_NOT_FOUND (the `ai` package imports @opentelemetry/api). Resolve the specifier first; only fall back to external when it can't be resolved. Installed → bundles into the self-contained output (Nitro, esbuild) and traces on node/nft targets; absent → external so Rollup/Vite (SvelteKit) doesn't fail the build. Verified: express Nitro build now inlines the package and its server loads with no node_modules present, and the peer-absent Vite 6/7 SSR build stays green via the external fallback. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… absent Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@opentelemetry/apiis an optional peer dependency the SDK loads lazily inside a try/catch. When it isn't installed, SvelteKit's Rollup pipeline turns the unresolvableimport('@opentelemetry/api')into a fatal build error:This blocked upgrading SvelteKit apps (that don't install the peer) to workflow v5-beta.
Fix
In the shared
@workflow/rolluptransform plugin (used by SvelteKit, Nitro, Nuxt, Astro, and the Vite integration), externalize@opentelemetry/apionly when it can't be resolved:.output/server, esbuild) that ship nonode_modules— forcing it external there strands the runtime import and crashes the server withERR_MODULE_NOT_FOUND.try/catchthen disables tracing.Externalizing (rather than aliasing to an empty stub) is deliberate — a stub would permanently disable tracing even when the peer is present.
Why not make the import opaque?
An earlier revision built the specifier at runtime (
['@opentelemetry','api'].join('/')) so bundlers couldn't follow it. That fixed the SvelteKit build but silently disabled tracing on esbuild/Nitro self-contained targets — the CLI'svercel-build-output-apibuild, Nitro, and Astro ship a bundle with nonode_modules, so an opaque import can't be inlined and resolves to nothing at runtime (this included theexamplee2e deployment). Keeping the import static lets esbuild inline@opentelemetry/apiand lets@vercel/nfttrace it, so tracing keeps working across all targets.Verification
Rollup failed to resolve import "@opentelemetry/api"error; the conditional external makes it pass. (Vite 8 no longer treats it as fatal, but externalizing is the version-robust fix.)expressworkbench) bundles@opentelemetry/apiinto.output/server, and the server module evaluates with nonode_modulespresent (noERR_MODULE_NOT_FOUND). CI: all Nitro local lanes (express/fastify/hono/nitro/tanstack) green.examplevercel-build-output-apibundle inlines@opentelemetry/apifor the SDK's tracing path, so OTEL works on the BOA e2e lane. CI: sveltekit / nuxt / astro / vite / example Vercel-prod lanes green.@workflow/rollupregression test covering both paths (present → bundle, absent → external).@opentelemetry/apidirectly inworkbench/example(aligning it with the other workbenches) and documented the optional peer in the tracing guide.Docs Preview