runtime:build

The bundler, from a program.

rolldown is already inside esdev — it is what esdev build runs. What was missing was a way for a program to reach it. Without that, a framework's dev server has to import rolldown from "rolldown", which is a napi addon this runtime does not load; so the dev server has to be a Node program, which is the thing it was trying to stop being.

Import

import { build, resolve } from "runtime:build";

build(options)

const bundle = await build({
  input: "app/main.jsx",
  external: (id) => id.startsWith("/__route/"),
  resolve: { alias: { "@": "./src" }, extensions: [".js", ".jsx"] },
  define: { "process.env.NODE_ENV": '"development"' },
  plugins: [mdx, css],
});

const { output, watchFiles } = await bundle.generate({
  format: "esm",
  codeSplitting: false,
});

serve(output[0].code);      // never written to disk

Output options (format, exports, dir, codeSplitting, sourcemap, entryFileNames, …) may be given here or per call to generate()/write(); the per-call ones win.

What a platform asserts

The same resolution defaults esdev build uses, from the same place — a project that resolves one way through the subcommand and another way through this module is a build bug nothing reports, and the bundle dies later on an import.

worker is the key a Web-API-targeting package uses for the build that does not reach for node: modules: react-dom/server resolves to its Web Streams implementation under it, and to a node:stream one without. browser is the other half — a client bundle built with worker asserted gets the build that expects no document. They are alternatives, not additions, because conditions match in the order the package author wrote them, so the wrong one being present at all is enough to win.

mainFields is what resolves a package too old to have an exports map. A neutral platform leaves it empty, so without it such a package does not resolve at all.

resolve(specifier, from)

The URL specifier names when imported from from — an absolute URL, string or URL, and a directory when it ends in / — rather than from the calling module. Synchronous.

import { resolve } from "runtime:build";

const root = new URL("./", `file://${cwd()}/`);   // cwd from runtime:process
resolve("@opentf/web", root);                      // the project's copy of the package
resolve("./app/page.jsx", root);                   // a file in the project

It answers as an import written at from would, through the run's own loader: the root jail, the import policy, the project's aliases and CommonJS conversion. So the target must exist, and a denied run gets a NotAllowedError.

import.meta.resolve takes one argument, as the standard defines it; this is the second half, for tools that run under esdev. See import.meta across runtimes.

Bundle

BuildResult

watchFiles is the reason this returns more than code. Paired with runtime:watch, it is what lets a dev server drop the three cached chunks whose dependencies changed and keep the other thirty-seven — instead of clearing everything on every save, which is the same as having no cache.

facadeModuleId is the module a chunk is — the entry it was built for, or the module behind a dynamic import — and null for a shared chunk. It is how you find one entry's chunk; output.find((c) => c.isEntry) asks a different question, since an emitted worker chunk is an entry as well.

When a build fails

generate() and write() throw a BuildError, whose errors is every diagnostic of the batch — a thrown Error has one message, and hiding the other four behind "and 4 more" is how a build error becomes a bug report.

try {
  await bundle.write({ dir: "dist" });
} catch (err) {
  for (const e of err.errors) {
    overlay.show(`${e.id}:${e.line}:${e.column}`, e.frame ?? e.message);
  }
}

An error used to be a string — the module id, a colon and "Unexpected token" — so an overlay could name the file and then had to stop. The bundler computed the line, the column and the frame all along for its own terminal output.

A failure a plugin reported is filled in the same way. ctx.error("cannot compile this route") from a transform arrives with id set to the module the hook was called about, plugin set to the plugin's name, message set to what was said, and frame null — there is no span for it, and a frame that is the message a second time under a banner is not one. A plugin that crashed — a TypeError, something undefined — keeps its stack in message instead, because the first frame of that one is the line in the plugin.

Plugins

A plugin is an object with a name and hooks; a hook is an object carrying a handler, and rollup's bare-function shorthand is refused. The system is this project's own rather than the bundler's passed through — see Writing a plugin for how, and Internals: the bundler bridge for why and what it costs.

const mdx = {
  name: "mdx",
  transform: {
    filter: { id: /\.mdx$/ },
    handler(code, id, ctx) {
      const { js, meta } = compile(code, id);
      return { code: js, type: "jsx", dependsOn: [meta] };
    },
  },
};

The six hooks

null or nothing means not mine, and the next plugin gets a turn. Anything else must be the object — a bare string of code is refused by name. Data comes first and the context last, with nothing positional between them.

bundle: what the build produced

bundle runs once, after the graph has been split into chunks and before any of it is written. Each entry is a chunk — { type: "chunk", fileName, name, isEntry, isDynamicEntry, facadeModuleId, moduleIds, imports, dynamicImports } — or an asset, { type: "asset", fileName }.

Route-level modulepreload is the case it exists for: which chunk an entry became, what went into it and what it imports do not exist until the split, and the split happens after end. That is why end is handed null and not the bundle — it fires when the module graph is finished, when there are no chunks yet.

const preload = {
  name: "preload",
  bundle: {
    handler(output) {
      const entry = output.find((o) => o.facadeModuleId === routeModule);
      manifest[route] = [entry.fileName, ...entry.imports];
    },
  },
};

It is read-only, and carries no code. Rollup lets a plugin rewrite chunks in the equivalent hook, which is how one plugin comes to invalidate the source maps of every plugin after it; and the bytes are what generate() already returns, so copying every chunk into the isolate on each rebuild would be a cost paid by a hook that only wanted the shape.

A hook's answer

dependsOn is returned rather than declared through a side effect — there is no this.addWatchFile() — because a dependency you can forget to declare produces a build that serves stale output.

filter

Matched on the host's side, before anything crosses into the isolate — so an unfiltered transform costs one crossing per module in the graph. start, end and bundle run once for the whole build and cannot be filtered.

A filter has to name id, code or both. A bare filter: /\.mdx$/, a typo'd ID, rollup's include, an empty {} and an empty list of patterns are all refused where they were written, and so is a pattern the matcher cannot evaluate (lookbehind, backreferences). The reason none of them is a shrug: a filter with nothing the host recognises in it is not a narrower hook, it is every module in the graph — a hook with no filter is a hook that wants all of them. A transform that quietly became a catch-all runs on modules it was never written for, and says nothing about it.

order

"pre" runs before the unordered plugins, "post" after; within a group, declaration order. Anything else is refused.

ctx — the last argument, not this

An argument, so an arrow-function handler keeps it. Live only while its hook runs: stashing ctx and calling it later throws.

Rejections

Every declaration is read when build() is called, so a bad one rejects there rather than at generate().

Example: a dev server that rebuilds one route

import { build } from "runtime:build";
import { watch } from "runtime:watch";

const chunks = new Map();          // route → { code, deps }

async function bundleRoute(route) {
  const b = await build({ input: route, plugins: [mdx] });
  const { output, watchFiles } = await b.generate({ codeSplitting: false });
  await b.close();
  chunks.set(route, { code: output[0].code, deps: new Set(watchFiles) });
  for (const file of watchFiles) changes.add(file);
}

const changes = watch(["app"], { recursive: true });
for await (const { path } of changes) {
  for (const [route, chunk] of chunks) {
    if (chunk.deps.has(path)) chunks.delete(route);   // only what used it
  }
}