Skip to content

runtime-next: browser and edge builds of the root entry - #50

Merged
sagnik11 merged 2 commits into
mainfrom
fix/runtime-next-browser-root
Nov 14, 2026
Merged

sagnik11 merged 2 commits into
mainfrom
fix/runtime-next-browser-root

Conversation

@sagnik11

@sagnik11 sagnik11 commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

What was wrong

@autter/runtime-next's root entry (exports["."]) only had types, import and require. Every bundler target, browser and edge included, got the server build, which re-exports @autter/runtime-node and with it @opentelemetry/sdk-node, gRPC, require-in-the-middle and fs.

That is fine for route handlers, but not for a module that both client and server code import. An error catalog that does import { defineRuntimeErrors } from "@autter/runtime-next" and is used by a client component broke the client build. The README warned about importing the root from client components, but the author of a shared module never writes a client import.

Pointing the browser condition at /client would not have been enough: the two entries export different names, so a shared module importing RuntimeError would fail with "export not found".

What changed

  • src/index.browser.ts (the browser condition) and src/index.edge.ts (edge-light / worker) export every name the server root exports (45 values), with the server types:
    • real: RuntimeError, defineRuntimeErrors, isRuntimeErrorLike, toClientError, errorAttributes, CODE_PATTERN, redactAttributes, redactText. The browser build bundles them from the private runtime-core. The edge build takes the error classes from @autter/runtime-edge, so a RuntimeError from a shared catalog is the same class that withAutter from @autter/runtime-next/edge checks.
    • no-op, warns once per name in development and is silent in production: captureServerException, captureServerMessage, reportServerOutcome, captureRequestError, trackLlmCall, addBreadcrumb, makeSafeCapture(), runtimeLogger, createRuntimeLogger(), runtimeContext. Wrappers still run the app's code (withRuntimeOperation, withProcessSpan, runInBackground, runtimeContext.fork), and instrumentLlmClient returns the client unchanged. These calls are not forwarded to the browser tracker.
    • inert values with no warning: flushRuntimeLogs, runtimeLogStats, the sink factories and the enrich* factories, because a shared config module may build them at import time.
    • throw a clear "server-only" error when called: registerAutter, withAutter, withRuntimeRequest, createAutterRelayRoute, withLlmCall, emitLlmSelftestTrace, initAutterLogging, installAutterAutoFlush, and the Express, Fastify and Koa hooks. The error names the function and points to /client (browser) or /edge (edge).
    • nothing runs at import time, and neither build imports @autter/runtime-node, @opentelemetry/* or node: modules.
  • package.json exports["."]: types, edge-light, worker, browser, import, require. This differs from the order first proposed (browser before the edge conditions). Next 16's edge compile also matches browser, so with browser first a runtime = "edge" route got the browser build (checked with Turbopack, see below). Node resolves the root to the server build as before, for both ESM and CJS.
  • tsup.config.ts: two blocks. The browser block uses platform: "browser" and es2020, because runtime-core contains BigInt literals. It keeps process.env.NODE_ENV for the app's bundler, since esbuild would otherwise bake in "development". The edge block uses platform: "neutral" and es2022. Both inline @autter/runtime-core and emit declarations, so the type check below also runs in CI.
  • Compile-time parity: each entry asserts that its value names equal the server root's and that every export is assignable to its server type. server-stand-ins.ts is typed as "every server-only root export", so adding a server export without a stand-in fails the build.
  • README: a new "Importing the root from shared modules" section replaces the old warning. CHANGELOG: entry under [Unreleased].
  • devDependencies: @autter/runtime-core (bundled, as runtime-node and runtime-edge already do) and esbuild (used by the test). No new runtime dependency.

How to test

npm ci
npm test -w @autter/runtime-next          # 35 tests, includes test/root-builds.test.mjs
(cd packages/runtime-next && npx tsc -p tsconfig.json)

test/root-builds.test.mjs covers:

  • export parity: dist/index.browser.{js,cjs} and dist/index.edge.{js,cjs} export exactly the server root's names, with matching typeof. On failure it lists the missing and extra names.
  • bundles: esbuild bundles a shared error-catalog module for browser, edge-light, edge-light + browser (Next webpack edge) and workerd + worker + browser (wrangler). It checks which build was picked and that the output has no node: import, no fs, no @opentelemetry, no require-in-the-middle and no @autter/runtime-node, and that no input file came from those packages.
  • stand-ins: no-ops never throw; they warn once per name with NODE_ENV=development and are silent with production; server-only functions throw the message described above; the real helpers behave like the server ones.
  • Node resolves @autter/runtime-next to dist/index.js (import) and dist/index.cjs (require).

Manual check with Next.js 16.4.5 (Turbopack): a throwaway app with lib/errors.js (imports defineRuntimeErrors, toClientError, captureServerException from the root), imported by a client component, a Node route that uses withAutter, and a runtime = "edge" route.

  • On main's exports map, next build exits 1 with module-not-found errors (gRPC, fs, …) in the Client Component Browser and Edge App Route graphs.
  • With this branch, next build exits 0. The client chunks contain no @opentelemetry, runtime-node or require-in-the-middle, and the edge route's source map lists runtime-next/dist/index.edge.js and runtime-edge, not runtime-node. next start serves the page with the catalog error rendered, /api/order returns 404 with toClientError JSON, and /api/edge-order returns 404.

Not covered

  • The Next 16 / Turbopack end-to-end job in CI (e2e/sourcemaps) was not extended. It is the ClickHouse-backed source-map check with exact assertions about .next output and one issue across four builds, and it has its own lockfile. Adding @autter/runtime-next and server and edge routes to it touches someone else's job, and I cannot run it fully without ClickHouse, so I ran the Next check above by hand instead. A small dedicated Next build step would need a ci.yml change.
  • @autter/runtime-next/server still has no browser or edge build, on purpose: it is the explicit server import.
  • No version bump. The release is separate; the analysis suggested runtime-next 1.10.0.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

sagnik11 and others added 2 commits November 15, 2026 02:29
The root's exports had no browser or edge condition, so every bundler got
the server build, which re-exports @autter/runtime-node (OpenTelemetry,
require-in-the-middle, fs). A module shared by client and server code,
such as an error catalog importing defineRuntimeErrors, broke the client
build.

- src/index.browser.ts ("browser") and src/index.edge.ts ("edge-light",
  "worker") export every name the server root exports, with its types:
  the coded-error and redaction helpers for real (bundled runtime-core;
  runtime-edge's classes on the edge), capture/log/context calls as
  no-ops that warn once in development, setup functions and server
  wrappers as functions that throw a "server-only" error when called.
- exports["."]: types, edge-light, worker, browser, import, require.
  Edge conditions come before "browser" because Next's edge compiles also
  match "browser" and would otherwise get the browser build.
- Compile-time parity check in both entries; tests for export parity
  (ESM and CJS), esbuild bundles for browser/edge-light/worker with no
  Node code, the stand-ins' behaviour, and Node resolution.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sagnik11
sagnik11 merged commit 9539559 into main Nov 14, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant