feat(vrowzer): build libraries in the browser with vrowzer.build()

[kazupon]

Part of #36. Stacked on #74 (rolldown 1.2.12).

vrowzer.build() builds the project for production in the browser. This PR is stage 1 of #36: the foundation (a build Worker, a snapshot of the project files and the Vite build core of upstream) and library builds.

// vite.config.ts
VrowzerPlugin({ build: true })

// application.ts
const { files, warnings } = await vrowzer.build({
  define: { __VERSION__: JSON.stringify('1.0.0') },
  build: { lib: { entry: '/src/index.ts', fileName: 'my-lib' }, sourcemap: true }
})
// files: { 'my-lib.js': '...', 'my-lib.js.map': '...', 'my-lib.css': '...' }

What it does

• build(options) takes a subset of the Vite config (base, mode, define and build), and resolves with { files, warnings }.
  • files is keyed by the path from the output root. JavaScript, CSS, source maps and text assets are strings, and binary assets are ArrayBuffers.
  • The files of /public are added unless build.copyPublicDir is false.
• Library builds (build.lib) in the es format:
  • JS/TS entries with their dependencies, CSS, assets, JSON and dynamic imports
  • one file with rolldownOptions.output.codeSplitting: false
  • JS minification (Oxc) and source maps
  • define, mode, import.meta.env and the plugin hooks of the Worker config
• The outputs run without the Service Worker, the dev RPC and the HMR client. The tests import them in Node.
• The build uses the project files as they are when build() is called: the files of ready(), with the default /index.html, and the file operations called before. Later changes do not reach the running build.
• One build at a time.
• A failed build rejects with VrowzerBuildError. Its errors have the message, code, plugin, module, location and frame of each error, without colors.
• buildTimeout (new, 120 s by default), signal and dispose() reject a build, and terminate its build Worker.
• Vrowzer({ build: true }) of @vrowzer/vite-plugin enables it. Without it, build() rejects with guidance, and the host output does not include the builder.

How it works

• Each build creates a build Worker (vrowzer/build-worker). It loads the builder (@vrowzer/vite-dev-server/builder), and runs upstream's build() with write: false on a virtual file system. The runtime terminates the build Worker when the build ends.
• The build Worker gets the Worker config of the previews, bundled again for production: process.env.NODE_ENV is "production", in node_modules/.vrowzer/config.build.bundled.mjs. Each build evaluates it in a new Worker, so the plugins start fresh.
• The runtime keeps a copy of the project files for the snapshot. The files the dev server adds (/dist/client/*.mjs) are not in it.
• The builder sets root: '/', configFile: false, build.write: false, build.emptyOutDir: false and logLevel: 'warn'. The options of build() are merged over the Worker config with Vite's mergeConfig().

Ported from upstream Vite 8.3.1

• build.ts: build(), createBuilder(), resolveConfigToBuild(), resolveRolldownOptions(), buildEnvironment(), the library helpers, the log handling, ChunkMetadataMap and the hook wrappers
• plugins/prepareOutDir.ts, and plugins/reporter.ts (the native reporter)
• oxcResolvePlugin(), the native resolve plugin, used by builds only
  • The JavaScript resolve plugin returns packageJsonPath: null, which rolldown 1.2.12 rejects in a build.
  • The previews keep the JavaScript resolve plugin.
• resolveConfig() decides NODE_ENV at runtime, as upstream does. The bundles of vite-dev-server no longer fix it to "development". The dev Web Worker still gets "development".
• Commented out with NOTE(kazupon):
  • the watch mode, SSR webworker builds, DevTools and Vite Task
  • the build plugins of later stages: preload, the terser and esbuild minifiers, license, manifest and Worker builds
• config.tsconfig and build.chunkImportMap (Vite 8.3) are read without their types, until the config of the fork has them.
• The unit tests port upstream's tests of the library helpers, the option resolution and the log handling. They build with the Node rolldown of the same version.

Differences from the issue

• A build Worker for each build. The issue says "not per build invocation". In the spike, it took about 0.13 s to prepare a build Worker, while keeping one held about +189 MiB and +15 Workers (rolldown's threads). Terminating the Worker after each build keeps nothing between builds, and gives fresh plugins.
  • Chromium takes about 2 s to stop a terminated build Worker: one of rolldown's threads does not answer terminate(), and Chromium stops it by force after 2 s.
  • Short builds one after another piled up those Workers, and the 12th build in a row stalled every time. Disposing rolldown's WASI binding first did not help.
  • The last commit paces the build Workers. When 4 of them closed within the last 2.5 s, the next build waits before it creates its build Worker. Builds longer than that do not wait. The wait does not count toward buildTimeout.
  • An alternative for discussion: keep the build Worker for a few seconds and reuse it, evaluating the Worker config again for each build. Rapid builds would be faster (about 10 ms each in the spike), but it changes the design, so this PR does not do it.
• Libraries first. They need fewer build plugins, so the foundation could be checked with them first. HTML app builds come in stage 2.

Not supported yet

These reject with VrowzerBuildError (VROWZER_UNSUPPORTED_OPTION):

• HTML app builds (stage 2)
• formats other than es, and libraries with more than one entry
• CSS minification (build.cssMinify), and the terser and esbuild minifiers
• build.watch, SSR builds, manifests and license files

.env files, CSS Modules, tsconfig and production CJS dependencies come in stage 3. The builds are tested in Chromium only.

Other changes

• The chunked transformer build renames the bundled __vite__injectQuery helper in every chunk, as the single-file aggregate does, and a bundle check guards it.
  • The build code changes how rolldown groups the modules into chunks.
  • A chunk that declares the helper and also gets the host Vite's import of it fails to load, which stops the Web Worker of a Worker config that imports vite.
• Bundle checks also keep isProduction decided at runtime, and the builder's globalThis.Buffer set before rolldown's binding.
• rolldown's native plugins report an error without plugin or id, e.g. a TypeScript syntax error from builtin:vite-transform. The builder reads them from the message.

There are no breaking changes. With build: false (the default), the host output only gets a 142-byte stub of the build Worker.

Measurements

macOS arm64, Chromium, a small library:

• build(): 218 ms for the first build, 137–143 ms afterwards. Each includes creating the build Worker and loading the builder.
• Host output with build: true:
  • +1,371,174 bytes for the builder (web-worker-builder-*.js), and a build Worker entry of 1,664 bytes
  • rolldown's WASM and rolldown-worker.js are shared with the previews
• Memory: with builds spaced out, about +135 MiB right after builds, which the stopping Workers release.

Tests

All on macOS (arm64):

• vp run build, the type checks, oxlint, knip and the format check pass.

• Unit tests: 2098 passed, 3 skipped (124 new).

  • vite-dev-server:
    • NODE_ENV
    • the build plugins that resolveConfig() registers
    • the ported build.spec.ts tests
    • package resolution in library builds
    • the builder's helpers
  • vrowzer: build() with a fake Worker, covering the state checks, the snapshot, closing the Worker on every outcome, other build ids, VrowzerBuildError and the pacing.
  • vite-plugin: the option, the define, the bundle for builds and the entries of the build Worker.

• Integration tests:

  Project	Result
  fs	3 passed
  node-polyfill	769 passed, 6 skipped
  rolldown	4 passed
  service-worker-server	10 passed
  service-worker	27 passed
  unplugin-service-worker	63 passed, 1 skipped
  vrowzer	99 passed, 1 skipped (14 new)

  • build.integration-test.ts builds a library in the browser, and imports it in Node. It covers:
    • one file, and with and without minification
    • the snapshot, and a syntax error and its fix
    • an overlapping call, the timeout, an aborted signal and dispose()
    • 12 builds in a row, and the release of the Workers
    • unsupported options, and the previews and HMR after builds
  • The restart fixture checks that build() rejects without the option.

• e2e, with the Vite caches cleared first:

  • dev mode: 46 passed, 6 skipped
  • host build mode: 39 passed, 13 skipped
  • The framework projects (react, svelte, vue and worker-config) pass in both modes.