@bakery-framework/plugin-vue 2.1.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-vue",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Bakery vue plugin.",
   "keywords": [
     "bakery",
@@ -43,7 +43,7 @@
     "vue": "^3.5.38"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.1.1"
+    "@bakery-framework/core": "^2.2.0"
   },
   "engines": {
     "bun": ">=1.4.0"

package/src/build.ts

@@ -0,0 +1,500 @@
+import { mkdir, readdir, rename, rm } from 'node:fs/promises'
+import { clientDefines } from '@bakery-framework/core/compiler'
+import { Bakery, hostKey, hostStore } from '@bakery-framework/core/core/bakery'
+import { resolveHostConfig } from '@bakery-framework/core/core/config'
+import { errorMsg, Logger } from '@bakery-framework/core/logger'
+import { fs, toHash } from '@bakery-framework/core/utils'
+import {
+  BUILD_DIR,
+  BUILD_FORMAT,
+  BUILD_URL,
+  type BuildManifest,
+  type BuiltPage,
+  buildFingerprint,
+  layoutsUnder,
+  moduleServerData,
+} from './built'
+import {
+  componentCss,
+  componentScript,
+  ROOT_SERVER_DATA,
+  VueHandler,
+} from './handler'
+import { cacheDir, parseVueMeta, VUE_VERSION } from './utils'
+
+/**
+ * `bakery --build` for Vue pages: every page under every serve root bundled
+ * with `Bun.build`, into content-hashed chunks a production server hands out
+ * with immutable caching. Served unbundled, a page costs a request per
+ * component, per imported module and per package (48 to 51 for a cold admin
+ * page of a real app with 40 components); built, it costs the shell, the Vue
+ * runtime, its entry chunk with the chunks it shares with other pages, and
+ * its stylesheets.
+ *
+ * Components are compiled by the same function that serves them
+ * (`componentScript`), with their imports left for the bundler to resolve
+ * against the files on disk. Import-map keys stay out of the bundle, for the
+ * browser's import map to resolve: `vue` above all, since two copies of Vue
+ * in one page is broken reactivity, and the runtime at `/_vue/` is the copy
+ * every unbundled module already shares.
+ *
+ * A component's `<script server>` block never reaches the bundle, as it never
+ * reaches the browser. What reaches it is the expression the component reads
+ * its exports from: the page's HTML carries them, because a built page runs
+ * the blocks of every component it can reach (see `builtModuleData`).
+ */
+
+const logger = new Logger('vue')
+
+/**
+ * A stand-in name for a module, in the directory of the file it stands for.
+ *
+ * Two things need one. A page's entry compiles as a root script (mounted, not
+ * imported), so it is a different module from the same file imported as a
+ * component, and needs a name of its own. And Bun 1.4.2 refuses any path a
+ * plugin resolves to that contains `...` ("must be absolute when the
+ * namespace is file"), measured on `[...slug].vue` and `a...b.vue` alike,
+ * with `[id].vue` and `[x]y.vue` accepted: so every catch-all page needs one.
+ *
+ * In the real file's directory, so relative imports and package lookups
+ * resolve from where the file is.
+ */
+const RX_ALIAS = /__bakery_(page|file)_[a-z0-9]+\.[a-z]+$/
+
+function aliasFor(ctx: RootContext, file: string, page: boolean): string {
+  const ext = file.slice(file.lastIndexOf('.'))
+  const alias = `${fs.dirname(file)}/__bakery_${page ? 'page' : 'file'}_${toHash(file)}${ext}`
+  ctx.aliases.set(alias, { file, page })
+  return alias
+}
+
+/** A resolved path Bun can take: the file's own, or a stand-in when it needs one. */
+function resolved(ctx: RootContext, file: string): string {
+  return file.includes('...') ? aliasFor(ctx, file, false) : file
+}
+
+/** The serve roots to build: the base one, then each host's own. */
+function serveRoots(): { root: string; hostname: string }[] {
+  const base = fs.resolve(Bakery.config.root)
+  const roots = [{ root: base, hostname: '' }]
+  const seen = new Set([base])
+  // A host without a root of its own serves the base root's files, and the
+  // base build serves it: the bundle's scope ids and data keys depend on the
+  // files alone.
+  for (const [hostname, entry] of Object.entries(Bakery.config.hosts ?? {})) {
+    if (!entry.root) continue
+    const root = fs.resolve(entry.root)
+    if (seen.has(root)) continue
+    seen.add(root)
+    roots.push({ root, hostname: hostname.toLowerCase() })
+  }
+  return roots
+}
+
+/**
+ * Every `.vue` file under `root` a request could render as a page: not a
+ * layout, not `module-only`, and not a file the server refuses to serve, whose
+ * code would otherwise sit in a chunk anybody could fetch by name.
+ */
+async function discoverPages(root: string): Promise<string[]> {
+  const blocked = Bakery.config.blocked
+  const pages: string[] = []
+  for await (const found of new Bun.Glob('**/*.vue').scan({
+    cwd: root,
+    absolute: true,
+    onlyFiles: true,
+  })) {
+    const file = fs.resolve(found)
+    if (file.endsWith('/layout.vue')) continue
+    if (file.includes('/node_modules/')) continue
+    if (fs.isForbidden(file, root) || blocked?.match(file)) continue
+    const { meta } = parseVueMeta(await Bun.file(file).text())
+    if (meta.moduleOnly) continue
+    pages.push(file)
+  }
+  return pages.sort()
+}
+
+function isExternal(specifier: string, externals: string[]): boolean {
+  return externals.some(key =>
+    key.endsWith('/') ? specifier.startsWith(key) : specifier === key,
+  )
+}
+
+/**
+ * A specifier written the way served code writes it: from the serve root, and
+ * perhaps with a query. Resolved the way the handlers resolve the URL: the
+ * file, a `.js` name for a `.ts` file, or an extensionless name with its
+ * extension or its directory's index.
+ */
+function resolveRooted(root: string, specifier: string, importer: string) {
+  const clean = decodeURIComponent(specifier.replace(/[?#].*$/, ''))
+  const base = fs.resolve(root, `.${clean}`)
+  if (base !== root && !base.startsWith(`${root}/`)) {
+    throw new Error(
+      `${specifier}, imported by ${importer}, leaves the serve root`,
+    )
+  }
+  const candidates = [
+    base,
+    base.endsWith('.js') ? `${base.slice(0, -3)}.ts` : '',
+    `${base}.ts`,
+    `${base}.js`,
+    `${base}/index.ts`,
+    `${base}/index.js`,
+  ]
+  for (const candidate of candidates) {
+    if (candidate && fs.isFileSync(candidate)) return candidate
+  }
+  throw new Error(
+    `${specifier}, imported by ${importer}, names no file under ${root}`,
+  )
+}
+
+/** A served module injects an imported stylesheet; so does a bundled one. */
+function stylesheetModule(css: string): string {
+  return (
+    `(function(){var s=document.createElement('style');` +
+    `s.textContent=${JSON.stringify(css)};document.head.appendChild(s)})();` +
+    'export default null;'
+  )
+}
+
+interface RootContext {
+  root: string
+  externals: string[]
+  /** Components with a server block, as they are loaded: file to route path. */
+  serverModules: Map<string, string>
+  /** Stand-in names (`aliasFor`), to the file and whether it is a page. */
+  aliases: Map<string, { file: string; page: boolean }>
+}
+
+/** The real file a loaded path is, and whether it is a page's entry. */
+function realFile(ctx: RootContext, path: string) {
+  const normalized = fs.resolve(path)
+  return ctx.aliases.get(normalized) ?? { file: normalized, page: false }
+}
+
+/** One component, compiled for the bundle. */
+async function compileForBundle(ctx: RootContext, path: string) {
+  const { file, page: isPage } = realFile(ctx, path)
+  const relPath = fs.relative(ctx.root, file)
+  if (relPath === '..' || relPath.startsWith('../')) {
+    throw new Error(
+      `${file} is outside the serve root ${ctx.root}, and only components under it compile`,
+    )
+  }
+  const routePath = `/${relPath}`
+  const id = toHash(hostKey(relPath))
+  const disk = Bun.file(file)
+  const parsed = await VueHandler.parseVueFile(
+    id,
+    disk,
+    file,
+    disk.lastModified,
+  )
+  const hasServerBlock = Boolean(parsed.serverScript.trim())
+
+  if (!isPage && parsed.meta.pageOnly) {
+    throw new Error(
+      `${routePath} is page-only, and a component imports it: served unbundled, that import is refused`,
+    )
+  }
+  if (!isPage && hasServerBlock) ctx.serverModules.set(file, routePath)
+
+  return componentScript({
+    id,
+    routePath,
+    isRootScript: isPage,
+    parsed,
+    served: false,
+    serverData: hasServerBlock
+      ? isPage
+        ? ROOT_SERVER_DATA
+        : moduleServerData(routePath)
+      : undefined,
+  })
+}
+
+function bundlePlugin(ctx: RootContext): Bun.BunPlugin {
+  return {
+    name: 'bakery-vue-build',
+    setup(build) {
+      build.onResolve({ filter: RX_ALIAS }, args => ({ path: args.path }))
+
+      build.onResolve({ filter: /.*/ }, args => {
+        const specifier = args.path
+        if (isExternal(specifier, ctx.externals)) {
+          return { path: specifier, external: true }
+        }
+        if (specifier.startsWith('/') && !specifier.startsWith('//')) {
+          const file = resolveRooted(ctx.root, specifier, args.importer)
+          return { path: resolved(ctx, file) }
+        }
+        // A relative `.vue` import carrying the query served code adds.
+        const query = specifier.indexOf('?')
+        if (
+          query !== -1 &&
+          specifier.startsWith('.') &&
+          specifier.slice(0, query).endsWith('.vue')
+        ) {
+          const importer = realFile(ctx, args.importer).file
+          const file = fs.resolve(
+            fs.dirname(importer),
+            specifier.slice(0, query),
+          )
+          return { path: resolved(ctx, file) }
+        }
+        return undefined
+      })
+
+      build.onLoad({ filter: /\.vue$/ }, async args => ({
+        contents: await compileForBundle(ctx, args.path),
+        loader: 'js',
+      }))
+
+      // A stand-in for a script with `...` in its name: the real file's text.
+      build.onLoad(
+        { filter: /__bakery_file_[a-z0-9]+\.(ts|tsx|js|jsx|mjs)$/ },
+        async args => {
+          const { file } = realFile(ctx, args.path)
+          const ext = file.slice(file.lastIndexOf('.') + 1)
+          return {
+            contents: await Bun.file(file).text(),
+            loader: (ext === 'mjs' ? 'js' : ext) as 'ts' | 'tsx' | 'js' | 'jsx',
+          }
+        },
+      )
+
+      build.onLoad({ filter: /\.css$/ }, async args => ({
+        contents: stylesheetModule(await Bun.file(args.path).text()),
+        loader: 'js',
+      }))
+    },
+  }
+}
+
+/** A build message with the file and line it names, when it names one. */
+function describeBuildError(error: unknown): string {
+  const message = (error as { message?: string })?.message ?? errorMsg(error)
+  const position = (error as { position?: { file?: string; line?: number } })
+    ?.position
+  return position?.file
+    ? `${position.file}:${position.line ?? 0}: ${message}`
+    : message
+}
+
+type Metafile = NonNullable<Bun.BuildOutput['metafile']>
+
+/** Every output reached from `start`, through the import kinds given. */
+function reachable(
+  outputs: Metafile['outputs'],
+  start: string,
+  kinds: string[],
+): string[] {
+  const seen = new Set([start])
+  const queue = [start]
+  while (queue.length) {
+    for (const edge of outputs[queue.pop()!]?.imports ?? []) {
+      if (!kinds.includes(edge.kind) || !(edge.path in outputs)) continue
+      if (seen.has(edge.path)) continue
+      seen.add(edge.path)
+      queue.push(edge.path)
+    }
+  }
+  return [...seen]
+}
+
+/** A metafile output name as the URL it is served under. */
+const servedAs = (output: string) =>
+  `${BUILD_URL}${output.replace(/^\.\//, '')}`
+
+/** A stylesheet, written once under a name its content decides. */
+async function writeStylesheet(outdir: string, css: string): Promise<string> {
+  const name = `s-${toHash(css)}.css`
+  await Bun.write(`${outdir}/${name}`, css)
+  return `${BUILD_URL}${name}`
+}
+
+/** The page's stylesheets, as `handleHtml` links them unbundled: layout first. */
+async function pageStylesheets(
+  root: string,
+  page: string,
+  outdir: string,
+): Promise<string[]> {
+  const relPath = fs.relative(root, page)
+  const id = toHash(hostKey(relPath))
+  const disk = Bun.file(page)
+  const parsed = await VueHandler.parseVueFile(
+    id,
+    disk,
+    page,
+    disk.lastModified,
+  )
+
+  const urls: string[] = []
+  if (parsed.layoutRoute) {
+    const layoutFile = fs.resolve(root, `.${parsed.layoutRoute}`)
+    const layoutId = toHash(hostKey(parsed.layoutRoute.slice(1)))
+    const layoutDisk = Bun.file(layoutFile)
+    const layout = await VueHandler.parseVueFile(
+      layoutId,
+      layoutDisk,
+      layoutFile,
+      layoutDisk.lastModified,
+    )
+    const css = await componentCss(layoutId, layout)
+    if (css) urls.push(await writeStylesheet(outdir, css))
+  }
+  const css = await componentCss(id, parsed)
+  if (css) urls.push(await writeStylesheet(outdir, css))
+  return urls
+}
+
+async function buildRoot(
+  root: string,
+  outdir: string,
+  manifest: BuildManifest,
+): Promise<number> {
+  manifest.layouts[root] = await layoutsUnder(root)
+  manifest.roots[root] = {}
+  const pages = await discoverPages(root)
+  if (!pages.length) return 0
+
+  const ctx: RootContext = {
+    root,
+    externals: Object.keys(Bakery.config.importMap ?? {}),
+    serverModules: new Map(),
+    aliases: new Map(),
+  }
+
+  let result: Bun.BuildOutput
+  try {
+    result = await Bun.build({
+      entrypoints: pages.map(page => aliasFor(ctx, page, true)),
+      outdir,
+      target: 'browser',
+      format: 'esm',
+      splitting: true,
+      minify: true,
+      metafile: true,
+      define: await clientDefines(),
+      // Names from content alone: a file's name changes exactly when its
+      // bytes do, which is what makes immutable caching true. No source
+      // names either, since `[...slug]` is not a name a URL carries well.
+      naming: {
+        entry: 'p-[hash].[ext]',
+        chunk: 'c-[hash].[ext]',
+        asset: 'a-[hash].[ext]',
+      },
+      plugins: [bundlePlugin(ctx)],
+    })
+  } catch (error) {
+    // Bun throws an AggregateError whose message is only "Bundle failed";
+    // what failed, and where, is in its `errors`.
+    const causes = (error as { errors?: unknown[] }).errors ?? [error]
+    const detail = causes.map(describeBuildError).join('\n  ')
+    throw new Error(`bundling the pages under ${root} failed:\n  ${detail}`)
+  }
+  if (!result.success || !result.metafile) {
+    const logs = result.logs.map(log => log.message).join('\n  ')
+    throw new Error(`bundling the pages under ${root} failed:\n  ${logs}`)
+  }
+
+  const { inputs, outputs } = result.metafile
+  const cwd = process.cwd()
+  const absolute = (path: string) => realFile(ctx, fs.resolve(cwd, path)).file
+
+  for (const input of Object.keys(inputs)) {
+    const file = absolute(input)
+    manifest.inputs[file] = Bun.file(file).lastModified
+  }
+
+  for (const [output, meta] of Object.entries(outputs)) {
+    if (!meta.entryPoint) continue
+    const page = absolute(meta.entryPoint)
+
+    const preload = reachable(outputs, output, ['import-statement'])
+      .filter(name => name !== output)
+      .map(servedAs)
+
+    const reached = new Set<string>()
+    for (const name of reachable(outputs, output, [
+      'import-statement',
+      'dynamic-import',
+    ])) {
+      for (const input of Object.keys(outputs[name]?.inputs ?? {})) {
+        reached.add(absolute(input))
+      }
+    }
+    const serverModules = [...reached]
+      .flatMap(file => ctx.serverModules.get(file) ?? [])
+      .sort()
+
+    const built: BuiltPage = {
+      script: servedAs(output),
+      preload,
+      css: await pageStylesheets(root, page, outdir),
+      serverModules,
+    }
+    manifest.roots[root][page] = built
+  }
+  return pages.length
+}
+
+/** `bakery --build`'s work for Vue: returns the manifest it wrote. */
+export async function buildVuePages(): Promise<BuildManifest> {
+  const started = performance.now()
+
+  // What a build killed part way left behind: it never reached the swap, so
+  // nothing reads it, and nothing else would ever remove it.
+  for (const name of await readdir(cacheDir).catch(() => [] as string[])) {
+    if (/^build-\d+-\d+$/.test(name)) {
+      await rm(fs.resolve(cacheDir, name), { recursive: true, force: true })
+    }
+  }
+
+  const temp = fs.resolve(cacheDir, `build-${process.pid}-${Date.now()}`)
+  await mkdir(temp, { recursive: true })
+
+  const manifest: BuildManifest = {
+    format: BUILD_FORMAT,
+    vue: VUE_VERSION,
+    fingerprint: buildFingerprint(),
+    inputs: {},
+    layouts: {},
+    files: [],
+    roots: {},
+  }
+
+  let pages = 0
+  try {
+    for (const { root, hostname } of serveRoots()) {
+      const run = () => buildRoot(root, temp, manifest)
+      pages += hostname
+        ? await hostStore.run(
+            { hostname, config: resolveHostConfig(hostname) },
+            run,
+          )
+        : await run()
+    }
+
+    manifest.files = (await readdir(temp)).sort()
+    await Bun.write(`${temp}/manifest.json`, JSON.stringify(manifest))
+
+    // Swapped in whole, so a server never reads half of one build and half
+    // of another.
+    await rm(BUILD_DIR, { recursive: true, force: true })
+    await rename(temp, BUILD_DIR)
+  } catch (error) {
+    await rm(temp, { recursive: true, force: true })
+    throw error
+  }
+
+  const ms = Math.round(performance.now() - started)
+  logger.log(
+    `Built ${pages} page${pages === 1 ? '' : 's'} into ${manifest.files.length} files in ${ms} ms (.cache/vue/build)`,
+    'info',
+  )
+  return manifest
+}

package/src/built.ts

@@ -0,0 +1,212 @@
+import { Bakery } from '@bakery-framework/core/core/bakery'
+import { Logger } from '@bakery-framework/core/logger'
+import { fs, toHash } from '@bakery-framework/core/utils'
+import { vueBuildVariant, vuePluginOptionsFingerprint } from './compile'
+import { cacheDir, VUE_VERSION } from './utils'
+
+/**
+ * What `bakery --build` leaves behind, and what a production server reads of
+ * it. The bundler itself is `build.ts`, which the server never loads.
+ */
+
+const logger = new Logger('vue')
+
+/** Where the build lives: disposable, like the rest of `.cache/`. */
+export const BUILD_DIR = fs.resolve(cacheDir, 'build')
+
+/** The URL prefix the build's files are served under. */
+export const BUILD_URL = '/_vue/build/'
+
+/**
+ * Bumped when the manifest or the bundled code changes shape, so a server
+ * never reads a build an older plugin made.
+ */
+export const BUILD_FORMAT = 1
+
+/**
+ * Where a built page's HTML puts the exports of the server blocks of the
+ * components it reaches, keyed by route path.
+ */
+export const SERVER_MODULES_GLOBAL = '__vue_server_modules'
+
+/**
+ * What a bundled component with a `<script server>` block reads its exports
+ * from, in place of the data a served one has spliced in.
+ *
+ * A block that answered with a response instead of data (a middleware's 401,
+ * a redirect) is recorded as `{ __bakeryResponse: status }`, and the
+ * component throws as it loads. Served, the same answer fails the component's
+ * module request, which fails the import: the page breaks either way, and the
+ * error says why.
+ */
+export function moduleServerData(routePath: string): string {
+  const key = JSON.stringify(routePath)
+  const message = JSON.stringify(
+    `${routePath}: its <script server> block answered with a response, not data: HTTP `,
+  )
+  return (
+    `((d) => { if (d && d.__bakeryResponse) throw new Error(${message} + d.__bakeryResponse); return d || {} })` +
+    `((globalThis.${SERVER_MODULES_GLOBAL} || {})[${key}])`
+  )
+}
+
+/** One page, as the build made it. */
+export interface BuiltPage {
+  /** The entry chunk's URL. */
+  script: string
+  /** Chunks the entry imports statically, preloaded beside it. */
+  preload: string[]
+  /** Stylesheet URLs: the layout's first, then the page's. */
+  css: string[]
+  /**
+   * Route paths of the components the page can reach that carry a
+   * `<script server>` block. Their blocks run with the page request, and
+   * their exports arrive in the HTML.
+   */
+  serverModules: string[]
+}
+
+export interface BuildManifest {
+  format: number
+  /** The Vue the render functions were compiled for. */
+  vue: string
+  /** The plugin options and import map the build was made under. */
+  fingerprint: string
+  /** Every file the bundle read, with the mtime it had then. */
+  inputs: Record<string, number>
+  /** Each serve root's `layout.vue` files at build time. */
+  layouts: Record<string, string[]>
+  /** Every file under the build directory the server may hand out. */
+  files: string[]
+  /** Serve root, then page file, both absolute. */
+  roots: Record<string, Record<string, BuiltPage>>
+}
+
+/**
+ * The options and the import map the build depends on, as one value.
+ *
+ * Every import-map key is left out of the bundle for the browser to resolve,
+ * `vue` among them, so adding or removing one changes what the bundle should
+ * contain without touching a source file. The plugin's options change the
+ * compiled templates the same way.
+ */
+export function buildFingerprint(): string {
+  const keys = new Set(Object.keys(Bakery.config.importMap ?? {}))
+  for (const host of Object.values(Bakery.config.hosts ?? {})) {
+    for (const key of Object.keys(host.importMap ?? {})) keys.add(key)
+  }
+  return toHash(
+    JSON.stringify([
+      vueBuildVariant(),
+      vuePluginOptionsFingerprint(),
+      [...keys].sort(),
+    ]),
+  )
+}
+
+/** Each root's `layout.vue` files, sorted, for the manifest and the check. */
+export async function layoutsUnder(root: string): Promise<string[]> {
+  const found: string[] = []
+  for await (const file of new Bun.Glob('**/layout.vue').scan({
+    cwd: root,
+    absolute: true,
+    onlyFiles: true,
+  })) {
+    found.push(fs.resolve(file))
+  }
+  return found.sort()
+}
+
+/**
+ * Why the manifest no longer describes the app, or null when it still does.
+ *
+ * Inputs are compared by mtime, the same test every compile cache here uses.
+ * Layouts are listed separately because adding one changes what wraps a page
+ * without touching any file the build read.
+ */
+export async function staleReason(
+  manifest: BuildManifest,
+): Promise<string | null> {
+  if (manifest.format !== BUILD_FORMAT) {
+    return 'it was made by another version of the plugin'
+  }
+  if (manifest.vue !== VUE_VERSION) {
+    return `it was compiled for Vue ${manifest.vue}, and ${VUE_VERSION} is installed`
+  }
+  if (manifest.fingerprint !== buildFingerprint()) {
+    return 'the Vue plugin options or the import map changed'
+  }
+  for (const [path, mtime] of Object.entries(manifest.inputs)) {
+    const file = Bun.file(path)
+    if (!fs.exists(file)) return `${path} is gone`
+    if (file.lastModified !== mtime) return `${path} changed`
+  }
+  for (const [root, layouts] of Object.entries(manifest.layouts)) {
+    const now = await layoutsUnder(root)
+    if (now.join('\n') !== layouts.join('\n')) {
+      return `a layout.vue was added or removed under ${root}`
+    }
+  }
+  return null
+}
+
+let loaded: Promise<{
+  manifest: BuildManifest
+  files: Set<string>
+} | null> | null = null
+
+/**
+ * The build, once per process, or null: in development, when there is none,
+ * and when it no longer matches the app. Production has no watcher and the
+ * page tree only changes with a restart (see `claimedBeside`), so one check
+ * is the whole of it, and a server started before a build keeps serving what
+ * it found.
+ */
+export function loadBuild(): Promise<{
+  manifest: BuildManifest
+  files: Set<string>
+} | null> {
+  if (import.meta.env.PROD !== '1') return Promise.resolve(null)
+  loaded ??= readBuild()
+  return loaded
+}
+
+async function readBuild() {
+  const file = Bun.file(`${BUILD_DIR}/manifest.json`)
+  if (!(await file.exists())) return null
+
+  let manifest: BuildManifest
+  try {
+    manifest = (await file.json()) as BuildManifest
+  } catch (error) {
+    logger.log(
+      `The Vue build's manifest is unreadable (${String(error)}): pages are served unbundled until \`bakery --build\` runs again.`,
+      'warn',
+    )
+    return null
+  }
+
+  const reason = await staleReason(manifest)
+  if (reason) {
+    logger.log(
+      `The Vue build is out of date (${reason}): pages are served unbundled until \`bakery --build\` runs again.`,
+      'warn',
+    )
+    return null
+  }
+  return { manifest, files: new Set(manifest.files) }
+}
+
+/** The built page for a file under a root, or null to serve it unbundled. */
+export async function builtPage(
+  root: string,
+  file: string,
+): Promise<BuiltPage | null> {
+  const build = await loadBuild()
+  return build?.manifest.roots[fs.resolve(root)]?.[fs.resolve(file)] ?? null
+}
+
+/** Test seam (convention 9): forget the memoized build. */
+export function __resetBuild(): void {
+  loaded = null
+}

package/src/chunks.ts

@@ -2,6 +2,7 @@ import { Bakery } from '@bakery-framework/core/core/bakery'
 import { Logger } from '@bakery-framework/core/logger'
 import { fs, response } from '@bakery-framework/core/utils'
 import { ETag } from '@bakery-framework/core/utils/http'
+import { BUILD_DIR, BUILD_URL, loadBuild } from './built'
 import { vueBuildVariant } from './compile'
 import { VUE_VERSION } from './utils'
 
@@ -34,11 +35,28 @@ export function vueChunkPath(): string {
   return `${VUE_CHUNK_PREFIX}${VUE_VERSION}.${vueBuildVariant()}.js`
 }
 
+/**
+ * A file `bakery --build` made. Only a name the manifest lists is served, so
+ * nothing else under the build directory, and nothing a crafted path could
+ * reach outside it, is ever handed out. Every name carries its content's
+ * hash, which is what makes caching it for a year correct.
+ */
+async function serveBuiltFile(path: string, req: Request): Promise<Response> {
+  const build = await loadBuild()
+  const name = path.slice(BUILD_URL.length)
+  if (!build?.files.has(name)) return response.error('Not Found', 404)
+
+  const res = await ETag.sendFile(Bun.file(`${BUILD_DIR}/${name}`), req)
+  res.headers.set('Cache-Control', 'public, max-age=31536000, immutable')
+  return res
+}
+
 /** Serves the self-hosted Vue runtime that `Bakery.config.importMap` points at. */
 export async function serveVueChunk(
   path: string,
   req: Request,
 ): Promise<Response> {
+  if (path.startsWith(BUILD_URL)) return serveBuiltFile(path, req)
   if (path !== vueChunkPath()) {
     return response.error('Not Found', 404)
   }
@@ -66,7 +84,7 @@ export async function serveVueChunk(
         entrypoints: [sourcePath],
         target: 'browser',
         format: 'esm',
-        // `Boolean(...)`, not the flag directly: the mode flags are `'1'`/`''` 
+        // `Boolean(...)`, not the flag directly: the mode flags are `'1'`/`''`
         // strings (`core/init.ts`), and `Bun.build` **rejects** a non-boolean
         // `minify` rather than coercing it. Core's `compiler.ts` already wrapped
         // its three; this one did not, and the build would have thrown on every

package/src/compile.ts

@@ -80,6 +80,21 @@ export function vueBuildVariant(): 'runtime' | 'full' {
   return vuePluginOptions.build === 'full' ? 'full' : 'runtime'
 }
 
+/**
+ * The options that change what a template compiles to, as one string, for a
+ * build to record and a server to compare. Functions count by their source,
+ * which is as close as a running process can get to knowing they changed.
+ */
+export function vuePluginOptionsFingerprint(): string {
+  return JSON.stringify(
+    {
+      customElements: vuePluginOptions.customElements,
+      compilerOptions: vuePluginOptions.compilerOptions,
+    },
+    (_key, value) => (typeof value === 'function' ? String(value) : value),
+  )
+}
+
 export function resolveIsCustomElement(tag: string): boolean {
   const ce = vuePluginOptions?.customElements
   const userFn = vuePluginOptions?.compilerOptions?.isCustomElement

package/src/handler.ts

@@ -24,6 +24,7 @@ import {
   validateActionRequest,
   validateActionTarget,
 } from './actions'
+import { type BuiltPage, builtPage, SERVER_MODULES_GLOBAL } from './built'
 import { serveVueChunk, VUE_CHUNK_PREFIX } from './chunks'
 import {
   compileStyleBlock,
@@ -66,6 +67,12 @@ function requestNamesFile(path: string, routePath: string): boolean {
 
 const RX_SERVER_DATA_TOKEN = new RegExp(`\\b${VUE_SERVER_DATA_TOKEN}\\b`, 'g')
 
+/**
+ * What a root script reads its page's server data from: the global the shell
+ * assigns, so the cached or bundled script itself carries no user's data.
+ */
+export const ROOT_SERVER_DATA = '(globalThis.__vue_server || {})'
+
 /**
  * Compiled module code with the server-data token still in place. Components
  * with a `<script server>` block get per-request data, so the code cannot be
@@ -285,6 +292,99 @@ export function claimedBeside(catchAllFile: string): {
   return result
 }
 
+/**
+ * A component's browser code: what `?__vue_script` serves, and what
+ * `bakery --build` bundles, from one compile so the two cannot drift apart.
+ *
+ * `served` is the difference between them. A served module is fetched by
+ * URL, so its `.vue` imports gain `?__vue_script=module` and its relative
+ * imports become absolute (see `absolutizeRelativeImports`), and it is named
+ * for the browser's debugger. A bundled one keeps its specifiers as written
+ * for the bundler to resolve against the file on disk.
+ *
+ * `serverData` replaces the server-data token, which only a component with a
+ * `<script server>` block carries: the request's data spliced in, or the
+ * expression a root script or a bundled component reads it from.
+ */
+export async function componentScript(options: {
+  id: string
+  routePath: string
+  isRootScript: boolean
+  parsed: ParsedCacheEntry
+  serverData?: string
+  served: boolean
+}): Promise<string> {
+  const { id, routePath, isRootScript, parsed, serverData, served } = options
+  const compiled = await compileVueFile({
+    content: parsed.cleanContent,
+    filename: routePath,
+    id: parsed.scopeId || id,
+    isRootScript,
+    layoutRoute: isRootScript ? parsed.layoutRoute : null,
+  })
+
+  if (compiled.errors.length) {
+    // Thrown, not logged-and-served: a template Vue could not compile has
+    // the raw unparseable expression in its render function, so serving it
+    // is a browser-side SyntaxError behind a 200 and an empty page, the
+    // report that surfaced this described exactly that. The throw lands in
+    // the error registry as a 500 that names the file and the error, or
+    // fails `bakery --build` naming the same.
+    throw new Error(
+      `Vue compile failed (${routePath}): ${compiled.errors.join('; ')}`,
+    )
+  }
+
+  let code = compiled.code
+
+  if (served) {
+    if (code.includes('.vue"') || code.includes(".vue'")) {
+      code = rewriteVueImports(code)
+    }
+    // After the `.vue` rewrite, which only appends a query and leaves the
+    // specifier relative. See `absolutizeRelativeImports` for why relative
+    // imports cannot survive into the browser.
+    code = absolutizeRelativeImports(code, routePath)
+  }
+
+  if (serverData !== undefined) {
+    code = code.replace(RX_SERVER_DATA_TOKEN, () => serverData)
+  }
+
+  if (!isRootScript) {
+    for (const style of compiled.styles) {
+      if (style.code) {
+        code += `;\n(function(){var k='__vu_css_${id}';var s=document.getElementById(k)||(function(){var el=document.createElement('style');el.id=k;document.head.appendChild(el);return el})();s.textContent=${JSON.stringify(style.code)}})()`
+      }
+    }
+  }
+
+  if (served) {
+    const sourceURL =
+      routePath.replace(/^.*[\\/]/, '').replace(/\?.*$/, '') ||
+      (isRootScript ? 'root.vue' : 'module.vue')
+    code += `\n//# sourceURL=${sourceURL}`
+  }
+
+  return code
+}
+
+/** A component's stylesheet, scoped, or '' when it has no styles. */
+export async function componentCss(
+  id: string,
+  parsed: ParsedCacheEntry,
+): Promise<string> {
+  const compiled = await Promise.all(
+    parsed.styles.map(style =>
+      compileStyleBlock({ style, id: parsed.scopeId || id }),
+    ),
+  )
+  return compiled
+    .map(s => s.code)
+    .filter(Boolean)
+    .join('\n\n')
+}
+
 export class VueHandler extends DynamicHandler {
   static get config() {
     return {
@@ -306,6 +406,16 @@ export class VueHandler extends DynamicHandler {
 
   static handle = sharedHandler
 
+  /**
+   * The runtime chunks, stylesheets, root scripts, and module scripts of
+   * components with no server block: what `sharedHandler` marked while
+   * serving this request. Never a page, an action, or a module whose server
+   * block ran for it, since those run app code on every request.
+   */
+  static isAsset(_path: string, req: Request): boolean {
+    return servedAsAsset.has(req)
+  }
+
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: SFC parser
   static async parseVueFile(
     id: string,
@@ -414,61 +524,21 @@ export class VueHandler extends DynamicHandler {
     return parsed
   }
 
-  private static async buildScriptCode(
+  private static buildScriptCode(
     id: string,
     routePath: string,
     isRootScript: boolean,
     parsed: ParsedCacheEntry,
     serverDataReplacement?: string,
   ) {
-    const { cleanContent, scopeId } = parsed
-    const compiled = await compileVueFile({
-      content: cleanContent,
-      filename: routePath,
-      id: scopeId || id,
+    return componentScript({
+      id,
+      routePath,
       isRootScript,
-      layoutRoute: isRootScript ? parsed.layoutRoute : null,
+      parsed,
+      serverData: serverDataReplacement,
+      served: true,
     })
-
-    if (compiled.errors.length) {
-      // Thrown, not logged-and-served: a template Vue could not compile has
-      // the raw unparseable expression in its render function, so serving it
-      // is a browser-side SyntaxError behind a 200 and an empty page, the
-      // report that surfaced this described exactly that. The throw lands in
-      // the error registry as a 500 that names the file and the error.
-      throw new Error(
-        `Vue compile failed (${routePath}): ${compiled.errors.join('; ')}`,
-      )
-    }
-
-    let code = compiled.code
-
-    if (code.includes('.vue"') || code.includes(".vue'")) {
-      code = rewriteVueImports(code)
-    }
-    // After the `.vue` rewrite, which only appends a query and leaves the
-    // specifier relative. See `absolutizeRelativeImports` for why relative
-    // imports cannot survive into the browser.
-    code = absolutizeRelativeImports(code, routePath)
-
-    if (serverDataReplacement !== undefined) {
-      code = code.replace(RX_SERVER_DATA_TOKEN, () => serverDataReplacement)
-    }
-
-    if (!isRootScript) {
-      for (const style of compiled.styles) {
-        if (style.code) {
-          code += `;\n(function(){var k='__vu_css_${id}';var s=document.getElementById(k)||(function(){var el=document.createElement('style');el.id=k;document.head.appendChild(el);return el})();s.textContent=${JSON.stringify(style.code)}})()`
-        }
-      }
-    }
-
-    const sourceURL =
-      routePath.replace(/^.*[\\/]/, '').replace(/\?.*$/, '') ||
-      (isRootScript ? 'root.vue' : 'module.vue')
-    code += `\n//# sourceURL=${sourceURL}`
-
-    return code
   }
 
   static async handleScript(
@@ -501,9 +571,7 @@ export class VueHandler extends DynamicHandler {
         ? `${id}.root.${vueBuildVariant()}${layoutTag}.js`
         : `${id}.js`
       const replacement =
-        isRootScript && hasServerScript
-          ? '(globalThis.__vue_server || {})'
-          : undefined
+        isRootScript && hasServerScript ? ROOT_SERVER_DATA : undefined
 
       return await fs.getOrCreateCachedFile(dir, fileName, lastMod, () =>
         this.buildScriptCode(id, routePath, isRootScript, parsed, replacement),
@@ -529,23 +597,15 @@ export class VueHandler extends DynamicHandler {
   }
 
   static async handleCss(id: string, parsed: ParsedCacheEntry) {
-    const { lastMod, scopeId, styles } = parsed
-
     const dir = fs.resolve(cacheDir, 'css')
     const fileName = `${id}.css`
 
-    return await fs.getOrCreateCachedFile(dir, fileName, lastMod, async () => {
-      const compiled = await Promise.all(
-        styles.map(style => compileStyleBlock({ style, id: scopeId || id })),
-      )
-
-      const css = compiled
-        .map(s => s.code)
-        .filter(Boolean)
-        .join('\n\n')
-
-      return css || null
-    })
+    return await fs.getOrCreateCachedFile(
+      dir,
+      fileName,
+      parsed.lastMod,
+      async () => (await componentCss(id, parsed)) || null,
+    )
   }
 
   /**
@@ -602,6 +662,11 @@ export class VueHandler extends DynamicHandler {
      * server block (see `needsServerData`), so the URL only picks the file.
      */
     assetPath: string = routePath,
+    /**
+     * The page as `bakery --build` made it, with the exports of the server
+     * blocks it reaches. Absent, the page is served unbundled.
+     */
+    built?: { page: BuiltPage; moduleData?: Record<string, unknown> },
   ) {
     const { hasCss, serverScript } = parsed
     const assets = escapeHtml(assetPath)
@@ -628,9 +693,14 @@ export class VueHandler extends DynamicHandler {
       ? `<script>globalThis.__vue_route = ${escapeScriptJson(route)};</script>`
       : ''
 
+    const moduleDecl =
+      built?.moduleData && Object.keys(built.moduleData).length
+        ? `<script>globalThis.${SERVER_MODULES_GLOBAL} = ${escapeScriptJson(built.moduleData)};</script>`
+        : ''
+
     let hydrated = VUE_HTML_SHELL.replace(
       '/*__SERVER_VARIABLES__*/',
-      () => serverDecl + routeDecl,
+      () => serverDecl + moduleDecl + routeDecl,
     )
 
     // Static markup, injected verbatim. See parseSkeleton for why it is
@@ -651,12 +721,26 @@ export class VueHandler extends DynamicHandler {
       )
     }
 
-    const prio =
-      (await VueHandler.layoutCssLink(parsed)) +
-      (hasCss
-        ? `<link rel="stylesheet" id="__vu_css_${id}" href="${assets}?__vue_css=true">\n`
-        : '') +
-      `<script type="module" src="${assets}?__vue_script=root"></script>`
+    // Built: the entry chunk, the chunks it imports announced beside it so
+    // the browser fetches them at once rather than after parsing the entry,
+    // and the build's stylesheets. The import map still comes first in the
+    // head (`injectIfHtml`): a module preload before it would settle module
+    // resolution without it.
+    const prio = built
+      ? built.page.css
+          .map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">\n`)
+          .join('') +
+        built.page.preload
+          .map(
+            href => `<link rel="modulepreload" href="${escapeHtml(href)}">\n`,
+          )
+          .join('') +
+        `<script type="module" src="${escapeHtml(built.page.script)}"></script>`
+      : (await VueHandler.layoutCssLink(parsed)) +
+        (hasCss
+          ? `<link rel="stylesheet" id="__vu_css_${id}" href="${assets}?__vue_css=true">\n`
+          : '') +
+        `<script type="module" src="${assets}?__vue_script=root"></script>`
 
     const htmlRes = await injectIfHtml(hydrated, params, { prio })
     return htmlRes || response.error('Failed to build HTML', 500)
@@ -713,6 +797,14 @@ async function serveIfDirect(value: any, req: Request) {
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: request handler, one branch per SFC render path
+/**
+ * Requests `sharedHandler` answered with an asset, for `VueHandler.isAsset`.
+ * Weak, so an entry lives exactly as long as its request. Recorded by the
+ * branch that serves the asset rather than worked out again from the query
+ * afterwards: the two would be one more pair of copies to keep in step.
+ */
+const servedAsAsset = new WeakSet<Request>()
+
 async function sharedHandler(
   this: typeof DynamicHandler | typeof DynamicErrorHandler,
   path: string,
@@ -720,6 +812,7 @@ async function sharedHandler(
   errors?: Handler.Error.Data,
 ) {
   if (path.startsWith(VUE_CHUNK_PREFIX)) {
+    servedAsAsset.add(req)
     return serveVueChunk(path, req)
   }
 
@@ -854,6 +947,7 @@ async function sharedHandler(
   const needsServerData = !isCss && vueScriptParam !== 'root'
 
   if (!needsServerData) {
+    servedAsAsset.add(req)
     if (isCss) return VueHandler.handleCss(id, parsed)
     return VueHandler.handleScript(id, routePath, true, parsed)
   }
@@ -872,10 +966,17 @@ async function sharedHandler(
   if (direct) return direct
 
   if (isScript) {
-    const serverValues = serverScript.trim() ? serverParams : undefined
+    const hasServerBlock = Boolean(serverScript.trim())
+    if (!hasServerBlock) servedAsAsset.add(req)
+    const serverValues = hasServerBlock ? serverParams : undefined
     return VueHandler.handleScript(id, routePath, false, parsed, serverValues)
   }
 
+  const page = await builtPage(Bakery.serveRoot, diskFile.name ?? '')
+  const built = page
+    ? { page, moduleData: await builtModuleData(page.serverModules, req) }
+    : undefined
+
   // `base` is the URL prefix the page owns: the file's directory. For
   // `wiki/[...page!].vue` that is `/wiki`; for a root-level catch-all it is
   // the empty string, which `defineLayout` treats as "everything".
@@ -899,5 +1000,55 @@ async function sharedHandler(
     // error render is the exception: its URL is the one that failed, and it
     // would route to the error, not to the error page's component.
     errorData ? routePath : url.pathname,
+    built,
+  )
+}
+
+/**
+ * The exports of the server blocks of the components a built page reaches,
+ * keyed by route path, for the page's HTML.
+ *
+ * Served unbundled, such a component's block runs when the browser fetches
+ * the component, with that request. Bundled, there is no such request, so
+ * the blocks run here, with the page's, side by side. What they see differs
+ * in one respect: `getRequest()` is the page request, with the page's URL.
+ * The body is empty, as a module request's always was.
+ *
+ * A block answering with a response rather than data is recorded with its
+ * status for the component to throw on (`moduleServerData`).
+ */
+async function builtModuleData(
+  routePaths: string[],
+  req: Request,
+): Promise<Record<string, unknown>> {
+  const entries = await Promise.all(
+    routePaths.map(async routePath => {
+      const file = fs.resolve(Bakery.serveRoot, `.${routePath}`)
+      const disk = Bun.file(file)
+      const relPath = routePath.slice(1)
+      const id = toHash(hostKey(relPath))
+      const parsed = await VueHandler.parseVueFile(
+        id,
+        disk,
+        file,
+        disk.lastModified,
+      )
+      const result = await getServerResponse({
+        script: parsed.serverScript,
+        id,
+        lastMod: disk.lastModified,
+        req,
+        body: {},
+        filePath: file,
+      })
+      const direct = asDirectResponse(result)
+      if (!direct) return [routePath, result] as const
+      const status =
+        direct instanceof Response || direct instanceof JsonResponseData
+          ? direct.status
+          : 200
+      return [routePath, { __bakeryResponse: status }] as const
+    }),
   )
+  return Object.fromEntries(entries)
 }

package/src/index.ts

@@ -72,6 +72,18 @@ export default function vuePlugin(options?: VuePluginOptions) {
      */
     onStart() {
       preloadCompiler()
+      // In production, read and check the build while the rest of boot runs,
+      // for the same reason; the first page awaits the same promise.
+      void import('./built').then(({ loadBuild }) => loadBuild())
+    },
+
+    /**
+     * `bakery --build`: every page bundled into content-hashed chunks, which
+     * a production server then serves in place of a request per module.
+     */
+    async build() {
+      const { buildVuePages } = await import('./build')
+      await buildVuePages()
     },
     onCompile(content, path) {
       if (