Repository navigation
runtime-next: browser and edge builds of the root entry - #50
Merged
Merged
Conversation
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>
…ser-root # Conflicts: # CHANGELOG.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was wrong
@autter/runtime-next's root entry (exports["."]) only hadtypes,importandrequire. Every bundler target, browser and edge included, got the server build, which re-exports@autter/runtime-nodeand with it@opentelemetry/sdk-node, gRPC,require-in-the-middleandfs.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
/clientwould not have been enough: the two entries export different names, so a shared module importingRuntimeErrorwould fail with "export not found".What changed
src/index.browser.ts(thebrowsercondition) andsrc/index.edge.ts(edge-light/worker) export every name the server root exports (45 values), with the server types:RuntimeError,defineRuntimeErrors,isRuntimeErrorLike,toClientError,errorAttributes,CODE_PATTERN,redactAttributes,redactText. The browser build bundles them from the privateruntime-core. The edge build takes the error classes from@autter/runtime-edge, so aRuntimeErrorfrom a shared catalog is the same class thatwithAutterfrom@autter/runtime-next/edgechecks.captureServerException,captureServerMessage,reportServerOutcome,captureRequestError,trackLlmCall,addBreadcrumb,makeSafeCapture(),runtimeLogger,createRuntimeLogger(),runtimeContext. Wrappers still run the app's code (withRuntimeOperation,withProcessSpan,runInBackground,runtimeContext.fork), andinstrumentLlmClientreturns the client unchanged. These calls are not forwarded to the browser tracker.flushRuntimeLogs,runtimeLogStats, the sink factories and theenrich*factories, because a shared config module may build them at import time.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).@autter/runtime-node,@opentelemetry/*ornode:modules.package.jsonexports["."]: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 matchesbrowser, so withbrowserfirst aruntime = "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 usesplatform: "browser"andes2020, because runtime-core contains BigInt literals. It keepsprocess.env.NODE_ENVfor the app's bundler, since esbuild would otherwise bake in"development". The edge block usesplatform: "neutral"andes2022. Both inline@autter/runtime-coreand emit declarations, so the type check below also runs in CI.server-stand-ins.tsis typed as "every server-only root export", so adding a server export without a stand-in fails the build.[Unreleased].@autter/runtime-core(bundled, as runtime-node and runtime-edge already do) andesbuild(used by the test). No new runtime dependency.How to test
test/root-builds.test.mjscovers:dist/index.browser.{js,cjs}anddist/index.edge.{js,cjs}export exactly the server root's names, with matchingtypeof. On failure it lists the missing and extra names.browser,edge-light,edge-light + browser(Next webpack edge) andworkerd + worker + browser(wrangler). It checks which build was picked and that the output has nonode:import, nofs, no@opentelemetry, norequire-in-the-middleand no@autter/runtime-node, and that no input file came from those packages.NODE_ENV=developmentand are silent withproduction; server-only functions throw the message described above; the real helpers behave like the server ones.@autter/runtime-nexttodist/index.js(import) anddist/index.cjs(require).Manual check with Next.js 16.4.5 (Turbopack): a throwaway app with
lib/errors.js(importsdefineRuntimeErrors,toClientError,captureServerExceptionfrom the root), imported by a client component, a Node route that useswithAutter, and aruntime = "edge"route.main's exports map,next buildexits 1 with module-not-found errors (gRPC,fs, …) in the Client Component Browser and Edge App Route graphs.next buildexits 0. The client chunks contain no@opentelemetry,runtime-nodeorrequire-in-the-middle, and the edge route's source map listsruntime-next/dist/index.edge.jsandruntime-edge, not runtime-node.next startserves the page with the catalog error rendered,/api/orderreturns 404 withtoClientErrorJSON, and/api/edge-orderreturns 404.Not covered
e2e/sourcemaps) was not extended. It is the ClickHouse-backed source-map check with exact assertions about.nextoutput and one issue across four builds, and it has its own lockfile. Adding@autter/runtime-nextand 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 aci.ymlchange.@autter/runtime-next/serverstill has no browser or edge build, on purpose: it is the explicit server import.🤖 Generated with Claude Code
Open in [code]smith · Need help on this PR? Tag
@codesmith-botwith what you need.