Build queue and adapter
Every server and browser build an app runs, in development and production, is a one-shot Rolldown build that goes through one queue. This page covers that path from request to result. Plugin pipeline covers the plugins a request carries, and Build pipeline what ecopages build asks for.
Config finalization creates one AppRuntime per app with its build adapter, build manifest, build-input index and build queue, and the runtime keeps that queue for its lifetime, so builds started during plugin and Integration setup share in-flight results with later ones. Runtime code reaches them through requireAppRuntime(appConfig) and requireBuildQueue(appConfig); a service given an unfinalized config fails with Missing app runtime instead of creating state of its own.
Requests
A request is a complete BuildOptions object, built by createServerBuildRequest() or createBrowserBuildRequest() in build/runtime/build-request-policy.ts. The queue only schedules; it adds no plugins.
Every request names environment: 'server' | 'browser'. The environment selects the platform, the default target and format, and which plugins take part; resolveBuildEnvironmentOptions() holds the defaults, one table per environment, and a request names only what differs. Browser requests define import.meta.env.NODE_ENV and process.env.NODE_ENV from the Ecopages process mode. An explicit numeric target changes transpilation without changing the environment.
createBuildRequestIdentity() identifies a request by every BuildOptions field except plugins, plus each plugin's name, environments and cacheKey in order. The source of setup is not hashed.
Lanes
The lane selects scheduling only; a browser request keeps its browser defaults on either lane.
| Lane | Used for | Limit |
|---|---|---|
build | ordinary server and browser builds | resolveBuildParallelism(): all logical CPUs but one, at least one |
hmr | the dev transform server and HMR browser rebuilds | three, or the build limit when lower |
nested | a build a running build waits for, such as the collection bundle a content plugin requests from onResolve | none |
The limited lanes start waiting builds in arrival order. A running build holds its lane's slot until it ends, so a child build in the same lane could wait for a slot its own parent holds; nested therefore has no limit, and the limited lane of the build at the top of each chain bounds how many run. Static export and the startup trace use the same resolveBuildParallelism() limit.
A request identical to a queued or running one shares that build, whichever lane it asks for. Inside BuildQueue.withRequestScope(), which the Node server adapter wraps around each development watch-mode request, a finished build is also shared with later identical requests of that scope. Production requests are not wrapped, and a build that rejects is never kept.
BrowserBundleService is the browser-build entry for asset processing and HMR: callers pass the lane explicitly, build for ordinary bundles and hmr for development rebuilds.
BuildOptions that map unusually
BuildOptions follows Rolldown's option shape. The exceptions:
splitting: falsewith one entry maps tocodeSplitting: false, so dynamic imports stay in one file. A worker entry is a second entry, so a module a script shares with its worker still gets its own chunk. With several entries, Rolldown cannot inline and ignores it.preserveModulesemits each source module as its own file, named after its source path with/replaced by-, so every module sits directly in the output directory; long names are shortened with a stable digest. Production server-module emit uses it so a shared SSR dependency keeps one output path, and therefore one module instance, across emit passes. Flat names keepimport.metaof every module pointing at the folder that holdsserverFiles, and keep relative externals resolvable from every module.sourcemapisnone,inline,external,linkedorhidden:linkedwrites a map and asourceMappingURL,externalandhiddenwrite a map without the link.workerEntriesapplies to browser builds and is on unlessfalse; see Worker entries.writeToDisk: falsecalls Rolldowngenerate()and returns outputs in memory; the dev vendor registry uses it to keep vendor bundles process-local.
Around the bridge's plugins the adapter adds a few native ones:
- Server-only guard, on browser-platform builds. It rejects any import of a Node builtin, with or without the
node:prefix, and any import of a.servermodule (extensionless./db.serverincluded). The check reads the resolved id, so an alias through apackage.jsonimportsentry or a tsconfig path fails like a relative import; a query or fragment does not change the result. A builtin is recorded where it resolves and reported when the build ends, once every module is parsed, so the error names the import chain from the app module through eachnode_modulesmodule to the builtin, and the.serverfix. Server builds allow.serverimports. An Integration may prune server-only imports before resolution, as React does when it strips server-only Page options. Noserver-onlypackage marker is read. - Stylesheet modules, on every build: a binding import of a stylesheet becomes the module
BuildOptions.stylesheets.compileModulereturns, and a side-effect import an empty module, except a package module's own import in a browser build, which fails it; see Stylesheet imports. - Installed-package externalizer, with
externalPackages; see Portable paths. - File role grammar, on every build: fails a module whose name puts a role segment anywhere but directly before a script extension; see Build pipeline.
- ssr script entries, on server builds that set
ssrScriptEntries; see Build pipeline. - Worker entries, on browser builds; see Worker entries.
buildRolldownInputPlugins() places them in the order listed in Plugin pipeline.
Server-only code in a browser build
isNodeBuiltinSpecifier(specifier) (utils/node-builtin.ts, exported from @ecopages/core/build) is the one answer to whether a specifier is a Node builtin: it starts with node:, or node:module lists it, subpaths such as fs/promises included. Why one owner: a package named like a builtin subpath (path-browserify) is not one, and the guard and the React client graph must not disagree. Two layers use it:
The first layer is an Integration's: React's client-graph boundary removes server-only imports before resolution, fails when the render function reaches one, and fails with the stripped-binding error when kept browser code still uses one (React). The guard is the backstop for every other path into the browser graph, a package that imports a builtin included. A package's own modules are not what the author wrote, so the chain walks each module's first importer until it leaves node_modules: imported from src/app.ts > node_modules/pg/lib/x.js > fs. Rolldown ids are native paths on Windows, so each link is converted with fromRolldownModuleId before the node_modules test.
Core's own hooks declare native filters, so Rolldown calls them only for the modules they handle: by id, or by code for the stylesheet module plugin's transform. The adapter enables experimental.nativeMagicString and closes its Rolldown bundle in a finally.
Results
BuildResult is a BuildSuccess or a BuildFailure, told apart by success.
- A
BuildFailurecarries onlylogs. A RolldownBundleErrorbecomes one log per underlying error; any other error, anAggregateErrorincluded, becomes one log (toBuildLogs). - A
BuildSuccesscarriesoutputs,warnings,dependencyGraph,entryOutputsandoutputGraph.dependencyGraph.entrypointsmaps each entry to its source-module closure, inlined and tree-shaken imports included, plus the files plugins declared withaddWatchFilefor a module in it. Cache owners bind exactly those paths in the build-input index, so a file one entry's plugin read never ties another entry's cache to it.dependencyGraph.commonJsEntrypointslists entries whose own module Rolldown read as CommonJS; their output hasmodule.exportsas its default export and no named exports, which the dev vendor graph relies on.entryOutputsis keyed by the path or grouped name the caller passed, plus Rolldown's facade path when that spelling differs, so a symlinked root or a different Windows drive case still finds the chunk. The adapter resolves each requested entry and its real path once per build (resolveRequestedBuildEntries) and matches every chunk's facade against that list, instead of resolving real paths again for each chunk. Look entries up withgetBuildEntryOutput, never by filename prefix.outputGraphgives static and dynamic chunk reachability without parsing emitted JavaScript.- Each
BuildOutputrecordscontentHashedwhen Rolldown named it by content.BrowserBundleServicewrites those paths to.ecopages-hashed-assetsbeside the outputs, and file serving appliesimmutablefrom that record, not from a filename guess.
Logs and warnings are BuildLogs: message plus, when Rolldown or the plugin provides them, code, plugin, hook, id, loc, frame and stack, with terminal colour codes stripped. Warnings come through Rolldown's onLog, so a failed build has none. formatBuildLog() is the one text form, [plugin] file:line:column: message then the frame and stack frames. assertBuildSucceeded() throws an error built from it, and buildOrThrow(appConfig, options, failure, lane) queues a build and does the same, so no caller joins log.message itself. Plugin pipeline covers how the bridge attributes an error to its plugin and module.
Worker entries
A browser build finds every new Worker(new URL('<literal>', import.meta.url), options), and the same with SharedWorker, after the bridge's transforms; type assertions and parentheses do not hide one.
- A URL starting with
./or../resolves like an import and becomes an entry of the same build, so the worker shares chunks with the page code. Thenew URL(...)expression becomes the emitted file's URL, and the importing chunk's hash follows the worker's file name. The worker takes the build's entry naming:[name]-[hash].jsin the app-wide build, or a fixed stem with its own hash in a build whose template has one. - The build fails when that URL does not resolve, carries a query or a hash, or starts a classic worker (no options, or a
typeother than'module'), because worker output is ESM and may import shared chunks. Options the build cannot read statically count as a module worker. An inline file script fails when it or a module it imports starts a worker entry, since an inline script resolvesimport.meta.urlagainst the page. - Any other URL, a Worker started from a non-literal expression, and every Worker URL under
node_modulesare left as written, with a build warning naming the file.
The app-wide browser build records the worker file in the asset ledger like any emitted file, so a sealed ecopages start serves it. The dev transform server builds with workerEntries: false and rewrites the URL itself; see Dev server.
Diagnostics
ECOPAGES_ROLLDOWN_BUILD_METRICS=1logs Rolldown invocation counts in development and production builds; bench and parity tests read the same counters.parseModuleSource()(cache/module-parse-cache.ts) memoizes Oxc parses that several build plugins request for the same source, keyed by path, content and options.
Sources
This page describes the code below.
packages/core/src/build/build-adapter.tspackages/core/src/build/build-parallelism.tspackages/core/src/build/build-log.tspackages/core/src/build/build-graph.tspackages/core/src/build/contracts/build-contracts.tspackages/core/src/build/runtime/packages/core/src/build/rolldown/rolldown-build-adapter.tspackages/core/src/build/rolldown/rolldown-adapter-helpers.tspackages/core/src/build/rolldown/rolldown-build-invocation-metrics.tspackages/core/src/build/rolldown/entry-module-closures.tspackages/core/src/build/rolldown/stylesheet-module-plugin.tspackages/core/src/build/rolldown/worker-entries-plugin.tspackages/core/src/build/rolldown/file-role-grammar-plugin.tspackages/core/src/build/rolldown/ssr-script-entries-plugin.tspackages/core/src/build/rolldown/rolldown-module-id.tspackages/core/src/utils/node-builtin.tspackages/core/src/build/worker-urls.tspackages/core/src/assets/browser-bundle.service.tspackages/core/src/cache/