build

What it does

Node-only. build renders every route of the route table to static HTML in outDir. Around the pages it bundles your CSS and client JS, copies images and public/, and writes feeds, a sitemap, OG images, a 404.html and Cloudflare _headers.

Add it to the Node app: createApp({ plugins: [buildPlugin] }). Run it with await app.build.run(), or through the cli plugin.

How it works

build orchestrates. It reads everything from other plugins through ctx.require: the routes from router, the head from head, the articles from content, the locales from i18n. It does no Markdown, head or URL work of its own. A run goes through fixed phases, in this order:

The phases from feeds to locale-redirects run together. When one fails, the error is logged and the others still finish. A disabled phase emits no build:phase event.

The JS entry is clientEntry, or the first file found of src/client/main.ts, src/client/main.tsx and src/main.ts. The CSS entry is src/client/styles.css or src/styles/main.css. Every page also gets a <meta name="build-id"> with the run id.

Config

pluginConfigs.build. Every field has a default.

OgImageConfig: fontDir (required, a folder with a .ttf, .otf or .woff file), template?, size? (default 1200 × 630), render?(input) => VNode, fonts?: OgFont[] and defaultCard?: boolean | ((input) => VNode). The config is shallow-merged, so an ogImage override replaces the whole object.

env: ["IS_DEVELOPMENT"] makes process.env.IS_DEVELOPMENT and import.meta.env.IS_DEVELOPMENT constants in the bundle, set to the build machine's value or "". With minify, a branch on an unset flag is removed together with the dynamic import() it guards.

API

Mounted at app.build, reachable with ctx.require(buildPlugin).

RunOptions: outDir? (this run only), skipClean?, overrides? (any of minify, feeds, sitemap, ogImage, images, localeRedirects, notFound, cacheHeaders for this run) and changed? (paths changed since the last run, for a fast incremental rebuild).

Events

Emits

Listens to

None.

Depends on

• site, router and head: required, in depends.
• content and i18n: optional. A site without content builds zero articles; without i18n it builds the "en" locale.
• data: optional. When composed and the mode is not "ssg", the pages phase writes the JSON sidecars.

Example

import { buildPlugin, createApp, createPlugin, defineRoutes, route } from "@moku-labs/web";
import { h } from "preact";

const routes = defineRoutes({
  home: route("/").render(() => h("h1", null, "My Blog")),
  about: route("/about/").render(() => h("p", null, "About"))
});

const timingPlugin = createPlugin("timing", {
  depends: [buildPlugin],
  hooks: ctx => ({
    "build:phase": ({ phase, status, durationMs }) => {
      if (status === "done") ctx.log.info("build:timing", { phase, durationMs });
    }
  })
});

const app = createApp({
  plugins: [buildPlugin, timingPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    build: { outDir: "dist", feeds: false, notFound: true }
  }
});

const result = await app.build.run();
console.log(`${result.pageCount} pages in ${result.durationMs}ms → ${result.outDir}`);

bun scripts/build.ts
{ level: "warn", event: "build:bundle", data: { clientEntry: "none", scanned: [ "src/client/main.ts", "src/client/main.tsx", "src/main.ts" ] } }
{ level: "info", event: "build:timing", data: { phase: "bundle", durationMs: 1 } }
{ level: "info", event: "build:timing", data: { phase: "pages", durationMs: 1 } }
{ level: "info", event: "build:timing", data: { phase: "root-index", durationMs: 0 } }
2 pages in 3ms → dist
ls dist
404.html  _headers  about  index.html  robots.txt  sitemap.xml

The log lines are shortened here: each one is a structured record from ctx.log. The warning says there is no client bundle, which is right for a site without islands.

Related

• Build & deploy: the scripts and the first deploy.
• Head & SEO: feeds, sitemap and OG images.
• Data: the JSON sidecars.