# Three layers

Source: https://moku-labs.com/docs/concepts/three-layers/ · @moku-labs/core@1.7.6

> createCoreConfig, createCore, createApp. Who writes what.

## The factory chain

Moku is a micro-kernel with three layers. Each layer constrains the one above it, and each step of
the chain captures its types in a closure, so the next step stays typed with no explicit generics.

```text
createCoreConfig(id, { config, plugins? })   Step 1: capture Config, Events, core plugins
  → { createPlugin, createCore }
createCore(coreConfig, { plugins, ... })     Step 2: capture the default plugins
  → { createApp, createPlugin }
createApp({ plugins?, config?, ... })        Step 3: merge the app's extras, run init
  → App  (frozen, plugin APIs mounted by name)
```

| Layer | Who writes it | Can | Cannot |
| --- | --- | --- | --- |
| 1. `@moku-labs/core` | the kernel | lifecycle, registry, events, config, freeze | know anything about a domain |
| 2. Framework, such as `@moku-labs/web` | the framework author | define the config shape, events, default plugins | change the kernel |
| 3. Your app | you, or an agent | configure, compose plugins, call typed APIs | change the framework or bypass a plugin |

## Layer 1: createCoreConfig

Pure machinery. The framework names itself, declares its global config shape and its event map,
and lists the core plugins that land on every `ctx`. `@moku-labs/web` calls it with the id `web`,
which is why every kernel error in this framework starts with `[web]`.

## Layer 2: createCore

The framework fixes its default plugins. An app can configure them but never remove or reorder
them. `@moku-labs/web` ships `site`, `i18n`, `router`, `head` and `spa` as defaults and exports
`createApp` and `createPlugin` to you.

| Option | Purpose |
| --- | --- |
| `plugins` | Default plugins, always loaded. |
| `pluginConfigs` | Framework-level overrides. |
| `onReady` | Runs after every `onInit`. |
| `onError` | Receives hook dispatch failures. Lifecycle errors propagate instead. |

## Layer 3: createApp

This is the layer you write. Everything comes from the framework: `createApp`, `createPlugin` and
the plugin instances.

```ts
import { createApp, createPlugin } from "@moku-labs/web";

const greetingPlugin = createPlugin("greeting", {
  config: { name: "world" },
  api: ctx => ({
    hello: () => `Hello, ${ctx.config.name}!`
  })
});

const app = createApp({
  plugins: [greetingPlugin],
  config: { mode: "ssg" },
  pluginConfigs: {
    site: { name: "My Site", url: "https://example.com" },
    greeting: { name: "Moku" }
  }
});

console.log(app.greeting.hello()); // "Hello, Moku!"
```

1. Added after the framework's defaults.
2. Per plugin, by name. Checked against the plugin's config type.

The final plugin list is `[...frameworkDefaults, ...yourPlugins]`. `createApp` is synchronous:
init runs before it returns.

## Rules

- **An app never imports `@moku-labs/core`.** It imports `createApp`, `createPlugin` and plugins
  from its framework.
- **Config is shallow.** `{ ...defaults, ...overrides }`. A nested object is replaced as a whole,
  so keep config flat.
- **Everything is frozen.** The global config, each plugin config and the app. Only `ctx.state`
  is mutable.


# Plugins

Source: https://moku-labs.com/docs/concepts/plugins/ · @moku-labs/core@1.7.6

> Every PluginSpec field, context tiers, core plugins.

## PluginSpec

Every field is optional. A plugin with only `api` works; a plugin with only `hooks` works.

```ts
createPlugin("name", {
  config:      { /* defaults, type C */ },
  events:      register => ({ "name:event": register<Payload>("description") }),
  depends:     [otherPlugin],
  createState: ctx => ({ /* mutable state, type S */ }),
  api:         ctx => ({ /* public methods, mounted on app.name */ }),
  hooks:       ctx => ({ "event:name": payload => { /* handler */ } }),
  onInit:      ctx => { /* all plugins exist; sync only */ },
  onStart:     async ctx => { /* app is running */ },
  onStop:      async ctx => { /* teardown, reverse order */ },
  helpers:     { /* static pure functions, no ctx */ }
});
```

| Field | Rule |
| --- | --- |
| `config` | Defaults. Shallow-merged with framework and app overrides, then frozen. |
| `events` | Declared with the register callback. Compile-time only. |
| `depends` | Plugins that must appear earlier in the list. Validation and typing only, no sorting. |
| `createState` | Called once with `{ global, config }`. Returns the only mutable store. |
| `api` | Synchronous, no side effects. Mounted at `app.<name>`. |
| `hooks` | Event handlers with the full `ctx`. Payloads are typed from the merged event map. |
| `onInit`, `onStart`, `onStop` | Lifecycle. See [Lifecycle](/docs/concepts/lifecycle/). |
| `helpers` | Pure functions on the instance, usable before `createApp`. |

Types are inferred from the spec. `createPlugin` never takes explicit generics.

## A plugin with state and a dependency

```ts
import { createApp, createPlugin } from "@moku-labs/web";

const clockPlugin = createPlugin("clock", {
  api: () => ({ now: () => Date.now() })
});

const counterPlugin = createPlugin("counter", {
  depends: [clockPlugin],
  config: { step: 1 },
  createState: () => ({ count: 0, lastAt: 0 }),
  api: ctx => ({
    increment: () => {
      ctx.state.count += ctx.config.step;
      ctx.state.lastAt = ctx.require(clockPlugin).now();
    },
    value: () => ctx.state.count
  })
});

const app = createApp({
  plugins: [clockPlugin, counterPlugin],
  pluginConfigs: { site: { name: "Demo", url: "https://example.com" }, counter: { step: 2 } }
});

app.counter.increment();
console.log(app.counter.value()); // 2
```

1. Must come earlier in the plugins list.
2. require takes the instance, not a string.
3. A closure over state, never the state object itself.

## Context tiers

The kernel hands each factory a context sized to its phase.

| Phase | `ctx` has |
| --- | --- |
| `createState` | `{ global, config }` |
| `api`, `hooks`, `onInit`, `onStart` | `{ global, config, state, emit, require, has }` plus core APIs such as `ctx.log` |
| `onStop` | `{ global, config, state }`: own data only, peers may already be stopped |

The type system enforces every restriction. Calling `ctx.emit` in `createState` is a compile error,
not a runtime surprise.

## Talking to other plugins

`ctx.require(plugin)` takes an instance and returns its typed API, or throws. `ctx.has(name)` is a
string check that never throws. Use `require` for request and response: events do not return
values.

## Core plugins

Infrastructure such as `log` and `env`. Their context is `{ config, state }` only. They cannot have
`depends`, `events` or `hooks`, and their APIs land flat on every regular plugin's `ctx`, not on
`app`. They init and start first, and stop last. In `@moku-labs/web` they are `log` and `env`, so
every plugin can call `ctx.log.info(...)`.

## Anti-patterns

- **Leaking state.** Return `value: () => ctx.state.count`, never `{ state: ctx.state }`.
- **God plugins.** One plugin per domain concern. Keep `index.ts` near 30 lines; logic goes in
  `api.ts` and its siblings.
- **`emit` for request and response.** Use `require(plugin)` to get a return value.
- **Inventing primitives.** No `class XService`, no `app.registerService()`. Write a plugin.


# Lifecycle

Source: https://moku-labs.com/docs/concepts/lifecycle/ · @moku-labs/core@1.7.6

> init, start, stop. Order, async model, failures.

## Three phases

| Phase | Method | Direction | When | Context |
| --- | --- | --- | --- | --- |
| init | `onInit` | forward | inside `createApp()`, synchronous | full `ctx` |
| start | `onStart` | forward | `await app.start()` | full `ctx` |
| stop | `onStop` | **reverse** | `await app.stop()` | own `global`, `config`, `state` |

Before the lifecycle, each plugin's factories run in this order:

1. `createState`
2. `hooks`
3. `api`
4. `onInit`
5. `onStart`
6. `onStop`

## Async model

One plugin at a time, fully awaited. There is no parallelism inside or across phases: plugin A
resolves before plugin B begins. `createApp()` is synchronous; `start()` and `stop()` return
promises.

```ts
import { createApp, createPlugin } from "@moku-labs/web";

const timerPlugin = createPlugin("timer", {
  createState: (): { handle?: ReturnType<typeof setInterval> } => ({}),
  onStart: ctx => {
    ctx.state.handle = setInterval(() => ctx.log.info("timer:tick"), 1000);
  },
  onStop: ctx => {
    clearInterval(ctx.state.handle);
  }
});

const app = createApp({
  plugins: [timerPlugin],
  pluginConfigs: { site: { name: "Demo", url: "https://example.com" } }
});

await app.start(); // onStart, forward, one plugin at a time
await app.stop(); // onStop, reverse: infrastructure outlives the plugins that use it
```

1. Open a resource when the app starts.
2. onStop gets its own state back, nothing else.

`onStart` and `onStop` are optional. Add them only when a plugin opens something it must close: a
socket, a listener, a timer.

## Failures

Lifecycle is not transactional. Errors propagate to the caller. The kernel does not roll back,
retry or compensate. After a failure, discard the app and create a new one.

`start()` throws when called twice, and `stop()` throws when `start()` never ran. The exact
messages are on [What the kernel checks](/docs/concepts/kernel-checks/).

## Core plugins

Core plugins have their own timeline: they init and start before regular plugins, and stop after
them. `ctx.log` therefore works in every `onStop` of a regular plugin's teardown chain, and the
logger is the last thing to go.

## In @moku-labs/web

Most web plugins only use `onInit`: `router` compiles its table, `site` and `i18n` validate their
config. `spa` is the one default with `onStart` and `onStop`, because it owns browser listeners.


# Events

Source: https://moku-labs.com/docs/concepts/events/ · @moku-labs/core@1.7.6

> Strict emit, the register callback, who sees what.

## Strict emit

Events are notifications: fire-and-forget, typed, no return value. Only known event names compile,
and the payload must match.

```ts
ctx.emit("auth:login", { userId: "123" }); // OK
ctx.emit("auth:login", { wrongKey: true }); // compile error: wrong payload
ctx.emit("unknown:event", {}); // compile error: unknown event
```

Handlers for one event run in plugin order, each awaited before the next. A handler error goes to
`onError`; it never stops the emitter.

## Declaring events

A plugin declares its own events with the register callback. The payload type comes from
`register<T>()`, so `createPlugin` still takes no generics.

```ts
import { createApp, createPlugin } from "@moku-labs/web";

const authPlugin = createPlugin("auth", {
  events: register => ({
    "auth:login": register<{ userId: string }>("Triggered after user login")
  }),
  api: ctx => ({
    login: (userId: string) => ctx.emit("auth:login", { userId })
  })
});

const auditPlugin = createPlugin("audit", {
  depends: [authPlugin],
  createState: (): { entries: string[] } => ({ entries: [] }),
  hooks: ctx => ({
    "auth:login": ({ userId }) => {
      ctx.state.entries.push(`login:${userId}`);
    }
  }),
  api: ctx => ({ entries: () => [...ctx.state.entries] })
});

const app = createApp({
  plugins: [authPlugin, auditPlugin],
  pluginConfigs: { site: { name: "Demo", url: "https://example.com" } }
});

app.auth.login("ada");
```

1. The description is documentation; the type is the contract.
2. depends makes auth's events visible to audit's hooks.

With a separate event-map type, use `register.map`:

```ts
type AuthEvents = { "auth:login": { userId: string }; "auth:logout": { userId: string } };

events: register =>
  register.map<AuthEvents>({
    "auth:login": "Triggered after user login",
    "auth:logout": "Triggered after user logout"
  });
```

## Who sees which events

| Source | Declared in | Visible to |
| --- | --- | --- |
| Global events | the framework's `createCoreConfig<Config, Events>` | all plugins |
| Own events | `events: register => ({ ... })` on the plugin | this plugin |
| Dependency events | `events` on plugins listed in `depends` | plugins that declare the dependency |

## Events in @moku-labs/web

| Event | Emitted by |
| --- | --- |
| `build:phase`, `build:complete` | `build` |
| `content:ready`, `content:invalidated` | `content` |
| `deploy:complete` | `deploy` |
| `spa:navigate`, `spa:navigated`, `spa:island-mount`, `spa:island-unmount` | `spa` |

> **Warning**
>
> Use `require`, not `emit`, for request and response. Events do not return values. Declaring
> `events` as a plain object instead of the register callback is refused when the plugin is created:
> see [What the kernel checks](/docs/concepts/kernel-checks/).


# What the kernel checks

Source: https://moku-labs.com/docs/concepts/kernel-checks/ · @moku-labs/core@1.7.6

> Seven checks and the exact error for each.

## When checks run

The kernel refuses a broken composition before any plugin code runs. Every failure is a thrown
error in two lines: what is wrong, then how to fix it. The first line starts with the framework id
in brackets. In `@moku-labs/web` that is `[web]`.

1. `createPlugin`: the plugin spec is checked, for example `events` must be a function.
2. `createApp`: names and dependencies are checked, before any `createState` or `onInit`.
3. `app.start()`: the app must not be started twice.

| Phase | What is checked |
| --- | --- |
| `createPlugin` | The shape of the spec. |
| `createApp` | Unique names, reserved names, core plugin names, every dependency present and earlier in the list. |
| `start` and `stop` | `start()` once per app, `stop()` only after `start()`. |

Type errors come first. Most mistakes on this page also fail `tsc`, so an editor shows them as you
type. The runtime checks catch the rest: a list built at runtime, a cast, plain JavaScript.

## The checks

Each message below is captured from the installed kernel when the site is built, by making the
mistake for real. It is never typed by hand, so it cannot drift from what your app prints.

- `duplicate-name` · checked at `createApp`

  ```text
  [web] Duplicate plugin name: "auth".
    Each plugin must have a unique name.
  ```

  Fix: List each plugin once in createApp({ plugins }).

- `missing-dependency` · checked at `createApp`

  ```text
  [web] Plugin "billing" depends on "auth", but "auth" is not registered.
    Add "auth" to your plugin list before "billing".
  ```

  Fix: Add the plugin it depends on to the plugins list.

- `dependency-order` · checked at `createApp`

  ```text
  [web] Plugin "billing" depends on "auth", but "auth" appears after "billing".
    Move "auth" before "billing" in your plugin list.
  ```

  Fix: Put a dependency before the plugin that depends on it.

- `reserved-name` · checked at `createApp`

  ```text
  [web] Plugin name "start" conflicts with a reserved app method.
    Choose a different plugin name.
  ```

  Fix: Rename the plugin: start, stop, emit and require are app methods.

- `core-plugin-clash` · checked at `createApp`

  ```text
  [web] Plugin name "log" conflicts with core plugin "log".
    Choose a different plugin name.
  ```

  Fix: Rename the plugin: log and env are core plugins on every ctx.

- `events-object` · checked at `createPlugin`

  ```text
  [web] Plugin "analytics" has invalid events: expected a function.
    Provide a function like: events: register => ({ "event:name": register<PayloadType>() })
  ```

  Fix: Declare events with a function: events: register => ({ ... }).

- `double-start` · checked at `start`

  ```text
  [web] App already started.
    start() can only be called once.
  ```

  Fix: Call app.start() once per app.

## Why errors and not warnings

An agent reads errors. It skims warnings. A startup error with the plugin name in it is the
cheapest review step in the lifecycle, so the kernel makes it impossible to skip.


# Claude plugin

Source: https://moku-labs.com/docs/claude/ · Claude plugin@0.85.6

> A conductor in Claude Code: idea → plan → build → verify → release, on rails.

## Overview

The `moku` plugin for Claude Code takes a project from an idea to a released package or a deployed
app, and keeps leading after that. Every later feature, fix and tweak travels the same lifecycle.

You never need a command. You talk; the conductor works out where the project stands, proposes the
next step and runs it. Underneath, the rails make the critical steps impossible to skip: no code
before the project is initialized, no plugin without a plan, no "done" with red tests.

- **Talk in plain words.** The conductor drives intake, brainstorm, design, plan, build, verify,
  e2e, release and close.
- **On rails.** A source file cannot be written before the station that is allowed to write it. A
  refused write names the missing step.
- **Knowledge loads itself.** `moku-core`, `moku-plugin` and `moku-testing`, plus one pack per
  framework such as `moku-web`.

## Install

In Claude Code, add the marketplace and install the core plugin:

```sh
/plugin marketplace add moku-labs/claude
/plugin install moku@moku
```

Then add the pack for each framework you use. Packs install the same way:

```sh
/plugin install moku-web@moku
/plugin install moku-design@moku
```

Requirements: Bun 1.3.14 or newer, Node 24 or newer, a current Claude Code.

## Stations

After a project exists, everything you bring becomes a **change** with a size. The size picks the
route.

| Size | Sign | Route |
| --- | --- | --- |
| S | one plugin, public API unchanged | intake → build → verify → close |
| M | new plugin, or an API changes | intake → plan → build → verify → e2e → release → close |
| L | several plugins, a new framework, an architecture shift | intake → brainstorm → design → plan → build → verify → e2e → release → close |

1. intake
2. plan
3. build
4. verify
5. release

Brainstorm, design, e2e and release are optional. Plan, build, verify and the closing checklist
(tests green, verify passed, docs current) are not.

> **Warning**
>
> The rails act only in a directory where a moku session was started. Your other projects get no
> gate, no hint and no hook output.

## Packs

| Pack | For |
| --- | --- |
| `moku-web` | `@moku-labs/web`, its validator, real-browser e2e with a UX gate |
| `moku-design` | the design station and Astra, the artist and second opinion on UX |
| `moku-worker` | `@moku-labs/worker`, the Cloudflare Workers backend |
| `moku-room` | `@moku-labs/room`, couch multiplayer |
| `moku-game` | `@moku-labs/game` and `@moku-labs/editor`, with the playtest station |
| `moku-ai` | `@moku-labs/ai`, AI asset builds with keys, providers and cost estimates |
| `moku-native` | `@moku-labs/native`, Tauri 2 desktop and mobile builds |
| `moku-system` | `@moku-labs/system`, store, notify, clipboard, tray and deep links |
| `moku-common` | `@moku-labs/common`, log, env and the branded CLI kit |

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/core

Source: https://moku-labs.com/docs/core/ · @moku-labs/core@1.7.6

> Micro-kernel plugin framework. Under 8 KB, zero deps. The kernel says no.

## Overview

Moku Core is the micro-kernel under every Moku framework. Two runtime exports, a bundle under
8 KB gzipped, zero dependencies. The type system does the heavy lifting.

It enforces three layers. The kernel is pure machinery. A framework defines the config shape, the
event contract and the default plugins. An app only configures, composes plugins and calls typed
APIs. Code written in a plugin cannot break the framework, and app code cannot break a plugin.

- **Each plugin owns its parts.** Config, state, API and events, resolved by the kernel.
- **Explicit dependencies.** `depends: [otherPlugin]`, validated when the app is created.
- **Strict emit.** Only known event names compile. A wrong payload is a type error.

> **Note**
>
> You build an app on a framework such as `@moku-labs/web`, never on the core directly. Install the
> core when you write a framework of your own.

## Install

```sh
bun add @moku-labs/core
```

## Quick start

A framework and an app in one file: `createCoreConfig` defines the framework, `createCore` fixes
its default plugins, `createApp` is what the app calls.

```ts
import { createCoreConfig } from "@moku-labs/core";

type Config = { siteName: string };
type Events = { "router:navigate": { from: string; to: string } };

const coreConfig = createCoreConfig<Config, Events>("my-site", {
  config: { siteName: "Untitled" }
});

const routerPlugin = coreConfig.createPlugin("router", {
  config: { basePath: "/" },
  createState: () => ({ currentPath: "/" }),
  api: ctx => ({
    navigate: (path: string) => {
      const from = ctx.state.currentPath;
      ctx.state.currentPath = path;
      ctx.emit("router:navigate", { from, to: path });
    },
    current: () => ctx.state.currentPath
  })
});

const framework = coreConfig.createCore(coreConfig, { plugins: [routerPlugin] });

const app = framework.createApp({
  config: { siteName: "My Blog" },
  pluginConfigs: { router: { basePath: "/blog" } }
});

await app.start();
app.router.navigate("/about");
await app.stop();
```

1. "my-site" prefixes every kernel error.
2. Fully typed: the API comes from the plugin spec.

The chain is the whole API: `createCoreConfig` → `createCore` → `createApp`. The second runtime
export, `createCorePlugin`, builds infrastructure plugins such as `log` and `env`.

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/common

Source: https://moku-labs.com/docs/common/ · @moku-labs/common@0.3.10

> Shared plugins: log, env, branded CLI.

## Overview

`@moku-labs/common` is a catalog of shared plugins for the Moku family. You author a plugin once
and reuse it in every framework. It has no `createApp` and no defaults of its own: you register its
plugins in your framework's `createCoreConfig`.

- **Write once, reuse everywhere.** Logging and env live here, not in every framework.
- **Core plugins.** Built with `createCorePlugin`, so their APIs land on every plugin's context as
  `ctx.log` and `ctx.env`.
- **A node-free browser entry.** `@moku-labs/common/browser` never pulls a `node:*` module into a
  client bundle. A CI gate proves it.

| Export | What it does |
| --- | --- |
| `logPlugin` | In-memory trace and an `expect()` DSL for testable workflows. Injected as `ctx.log`. |
| `envPlugin` | Validated, frozen environment from several providers. Injected as `ctx.env`. |
| `dotenv`, `processEnv`, `cloudflareBindings` | Env providers for Node and Workers. |
| `browserEnv` | Env provider for the browser, from `@moku-labs/common/browser`. |
| `createBrandConsole`, `createBrandPrompts` | The branded terminal kit, from `@moku-labs/common/cli`. |

## Install

```sh
bun add @moku-labs/common @moku-labs/core
```

## Quick start

Register the plugins in your framework's `createCoreConfig`. Every plugin then gets `ctx.log` and
`ctx.env`.

```ts
import { envPlugin, logPlugin } from "@moku-labs/common";
import { createCoreConfig } from "@moku-labs/core";

type Config = { stage: "production" | "development" };
type Events = {};

export const coreConfig = createCoreConfig<Config, Events, [typeof logPlugin, typeof envPlugin]>(
  "my-framework",
  {
    config: { stage: "production" },
    plugins: [logPlugin, envPlugin]
  }
);

export const greeterPlugin = coreConfig.createPlugin("greeter", {
  api: ctx => ({
    greet: (name: string) => ctx.log.info("greeter:greet", { name })
  })
});
```

1. ctx.log and ctx.env on every plugin.

Pick the env provider that matches each target:

```ts
import { dotenv, processEnv } from "@moku-labs/common"; // Node
import { browserEnv } from "@moku-labs/common/browser"; // browser, node-free
```

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/web

Source: https://moku-labs.com/docs/web/ · @moku-labs/web@2.4.11

> Content static-site generator and SPA framework. Same render at build and in the browser.

## What it is

`@moku-labs/web` renders Preact pages to static HTML for search engines and first paint. Then it
hydrates islands and, if you want it, navigates on the client from JSON. The same `render`
function runs at build and in the browser, so the two can never disagree.

It is a Moku framework: the `@moku-labs/core` kernel plus a list of plugins. You write one
`createApp` call. The browser-safe plugins are always there. You add the Node-only plugins for
the build.

### Five things it does

- **[SSG and SPA parity](/docs/web/how-it-works/).** One route, two runtimes. The build writes
  HTML, the browser re-runs the same `render` with the saved data.
- **[A typed route](/docs/web/guides/routing/).** `route("/{slug}/").load().render().head()`.
  Params come from the pattern, `ctx.data` from `load`.
- **[Full SEO](/docs/web/guides/head/).** Title template, canonical, Open Graph, Twitter,
  JSON-LD, hreflang, feeds, sitemap and OG images.
- **[A node-free browser entry](/docs/web/api/).** `@moku-labs/web/browser` has zero Node imports
  in its graph. About 50 kB gzip.
- **[Islands](/docs/web/guides/islands/).** Only the interactive parts run in the browser, each
  with its own state, render, events and API.

## Quick start

1. **Install** the framework and its peers: `bun add @moku-labs/web @moku-labs/core @moku-labs/common preact preact-render-to-string`.
2. **Write the routes** with `route()`: a pattern, a `load`, a `render`, a `head`.
3. **Compose the app** with `createApp`, adding `contentPlugin` and `buildPlugin` for the build.
4. **Build** with `await app.build.run()`. The site is in `dist/`.

A whole static blog fits in two files:

```tsx
import { defineRoutes, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  home: route("/")
    .render(() => <h1>My Blog</h1>)
    .head(() => ({ title: "My Blog" })),
  about: route("/about/")
    .render(() => <p>Notes on the web.</p>)
    .head(() => ({ title: "About" }))
});
```

1. `.head()` feeds the title template, canonical and OG tags.

The [quick start](/docs/web/quick-start/) goes from an empty folder to a deployed site.

## Two entry points

| Entry | Format | Use it for |
|---|---|---|
| `@moku-labs/web` | ESM and CJS | The Node build. Everything, including `buildPlugin`, `deployPlugin`, `cliPlugin`, `fileSystemContent` and the Node env providers. |
| `@moku-labs/web/browser` | ESM only | The client bundle. The same `createApp` over the same defaults, plus `dataPlugin`, the route helpers, `createIsland` and the head helpers. `env` reads `browserEnv()` with no config. |

## The eleven plugins

The defaults are loaded by every `createApp`. You can only configure them. The others you add in
`plugins: [...]`.

| Plugin | Kind | What it does |
|---|---|---|
| [site](/docs/web/plugins/site/) | default | Site name, URL, author, description, canonical URLs. |
| [i18n](/docs/web/plugins/i18n/) | default | Locales, default locale, translations, `og:locale` map. |
| [router](/docs/web/plugins/router/) | default | The route table, the matcher, URL and file paths, the render mode. |
| [head](/docs/web/plugins/head/) | default | The `<head>` of every page. |
| [spa](/docs/web/plugins/spa/) | default | Islands, intercepted navigation, progress bar. Inert on Node. |
| [content](/docs/web/plugins/content/) | Node build | Markdown articles to HTML, with locale fallback. |
| [collection](/docs/web/plugins/collection/) | optional | `(collection, shard)` → JSON file, read on demand. |
| [data](/docs/web/plugins/data/) | optional | Page path → JSON file, for client navigation. |
| [build](/docs/web/plugins/build/) | Node-only | The static build into `dist/`. |
| [deploy](/docs/web/plugins/deploy/) | Node-only | Cloudflare Pages through wrangler. |
| [cli](/docs/web/plugins/cli/) | Node-only | `build`, `serve`, `preview`, `deploy` with the branded panel. |

Two core plugins come with every app: `log` and `env`, from `@moku-labs/common`.

## Start with the Claude plugin

Install the moku plugin in Claude Code and describe the site in plain words. It knows this
framework, writes the routes, the islands and the tests, and runs the build.

```sh
$ /plugin marketplace add moku-labs/claude
$ /plugin install moku@moku-labs
```

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a search box that reads a JSON index built at deploy time
```

## Where to next

- [Quick start](/docs/web/quick-start/): a static blog in two files, client navigation in a third.
- [How it works](/docs/web/how-it-works/): one route, two places.
- [Routing](/docs/web/guides/routing/): `route().load().render().head()`, the single contract.
- [Islands](/docs/web/guides/islands/): the parts that run in the browser.
- [API reference](/docs/web/api/): every export of both entries.


# Quick start

Source: https://moku-labs.com/docs/web/quick-start/ · @moku-labs/web@2.4.11

> From an empty folder to a deployed static blog with client navigation.

## A static blog in eight steps

1. **Create the project and install.** `preact`, `preact-render-to-string`, `@moku-labs/core` and `@moku-labs/common` are peer dependencies. Declare them yourself: a second copy of Preact breaks hooks and island hydration.

   ```sh
   $ mkdir my-blog && cd my-blog
   $ bun init -y
   $ bun add @moku-labs/web @moku-labs/core @moku-labs/common preact preact-render-to-string
   ```

2. **Point JSX at Preact.** Routes and islands are `.tsx`. Without these two lines Bun looks for React and the build fails.

   ```json
   {
     "compilerOptions": {
       "jsx": "react-jsx",
       "jsxImportSource": "preact",
       "module": "Preserve",
       "moduleResolution": "bundler",
       "strict": true
     }
   }
   ```

3. **Add content.** One folder per article, one file per locale. The frontmatter fields `title`, `date`, `description`, `tags` and `language` are required.

   ```md
   ---
   title: Hello world
   date: 2026-01-15
   description: The first post.
   tags: [intro]
   language: en
   ---

   Some text.
   ```

4. **Write the routes.** A route is a pattern plus `generate`, `load`, `render` and `head`. `generate` and `load` run at build only. `render` and `head` run at build and in the browser.

5. **Compose the app.** The defaults (`site`, `i18n`, `router`, `head`, `spa`) are always there. Add the Node-only plugins the build needs.

6. **Add one script per command.** The `cli` plugin has no argument parser. Each script calls one method.

7. **Build.** `bun run build` writes static HTML, feeds, a sitemap and the JSON sidecars into `dist/`.

8. **Deploy.** `bun run deploy` runs a guided wizard: it checks the Cloudflare credentials, offers to scaffold `wrangler.jsonc`, test-builds and ships `dist/` to Cloudflare Pages.

## The code

The routes import from `@moku-labs/web/browser`, because the client bundle imports this file
too. The app imports from `@moku-labs/web`, the Node entry.

```tsx
import { contentPlugin, defineRoutes, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  home: route("/{lang:?}/")
    .generate(ctx => [{ lang: ctx.locale }])
    .load(async ctx => {
      const content = ctx.require(contentPlugin);
      const byLocale = await content.loadAll();
      return (byLocale.get(ctx.locale) ?? []).map(article => content.articleToCard(article));
    })
    .render(ctx => (
      <ul>
        {ctx.data.map(card => (
          <li key={card.contentId}>
            <a href={card.url}>{card.title}</a>
          </li>
        ))}
      </ul>
    ))
    .head(() => ({ title: "Home" })),
  post: route("/{lang:?}/{slug}/")
    .generate(async ctx => {
      const byLocale = await ctx.require(contentPlugin).loadAll();
      return (byLocale.get(ctx.locale) ?? []).map(article => ({
        lang: ctx.locale,
        slug: article.computed.slug
      }));
    })
    .load(ctx => ctx.require(contentPlugin).load(ctx.params.slug, ctx.locale))
    .render(ctx => <article dangerouslySetInnerHTML={{ __html: ctx.data.html }} />)
    .head(ctx => ({
      title: ctx.data.frontmatter.title,
      description: ctx.data.frontmatter.description
    }))
});
```

1. One home page per locale. Without `generate` only the default locale gets one.
2. Sibling plugins come through `ctx.require`. The return type becomes `ctx.data`.

```ts
import {
  buildPlugin,
  cliPlugin,
  contentPlugin,
  createApp,
  dataPlugin,
  deployPlugin,
  dotenv,
  fileSystemContent,
  processEnv
} from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, dataPlugin, buildPlugin, deployPlugin, cliPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
    router: { routes },
    head: { titleTemplate: "%s · My Blog" },
    content: { providers: [fileSystemContent({ contentDir: "content" })] },
    build: { clientEntry: "src/client.tsx", notFound: true },
    env: { providers: [processEnv(), dotenv(".env")] }
  }
});
```

1. Node-only plugins are opt-in. `dataPlugin` makes the build write the JSON sidecars.
2. `notFound: true` writes `dist/404.html`. `cli.build()` fails without it.

```ts
import { app } from "../src/app";

await app.cli.build();
```

```json
{
  "scripts": {
    "build": "bun scripts/build.ts",
    "dev": "bun scripts/serve.ts",
    "preview": "bun scripts/preview.ts",
    "deploy": "bun scripts/deploy.ts"
  }
}
```

`scripts/serve.ts` and `scripts/preview.ts` are the same two lines with `app.cli.serve()` and
`app.cli.preview()`. `scripts/deploy.ts` turns on the guided wizard unless `--cli` is passed:

```ts
import { app } from "../src/app";

await app.cli.deploy({ guided: !process.argv.includes("--cli") });
```

## Build

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ bundle · 5ms
✓ images · 0ms
✓ content · 1239ms
✓ pages · 5ms
✓ content-images · 0ms
✓ not-found · 1ms
✓ feeds · 2ms
✓ sitemap · 1ms
✓ cache-headers · 0ms
✓ root-index · 0ms
✓ BUILD · 9 pages                                1252ms · ./dist/
```

Nine pages from two articles, `hello-world` in English and Ukrainian and `second-post` in English only: the English pages at bare paths, a copy of each under `/en/`
with a canonical link to the bare URL, and the Ukrainian pages under `/uk/`. The second article
has no `uk.md`, so `/uk/second-post/` shows the English text.

## Add client navigation

The browser entry has the same `createApp` over the same defaults, with every Node-only module
left out. Name it in `build.clientEntry` and the build bundles it into `dist/assets/`.

```tsx
import { createApp, dataPlugin, defineRoutes, route } from "@moku-labs/web/browser";

const routes = defineRoutes({ home: route("/").render(() => <h1>My Blog</h1>) });

const app = createApp({
  plugins: [dataPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes }
  }
});

await app.start();
```

1. In your app, import the shared `./routes` here instead.
2. With `data` composed, a link click fetches the page JSON and runs the route's `render`.
3. Mounts islands on the static HTML and starts intercepting links.

The browser app needs the same `site`, `i18n` and `router` config as the Node app. Put the
shared values in one module and import it in both.

## Deploy

Put the Cloudflare credentials in `.env` (keep it out of git) and in the repository secrets for
CI. Then deploy.

```sh
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...
```

```sh
$ bun run deploy
▟▙ moku web  deploy                                      v2.4.11
✓ DEPLOYED · main                                             9.4s
→ https://my-blog.pages.dev · 3f2a9c1e
```

The project name is the site name as a slug: `My Blog` deploys to the Pages project `my-blog`.
See [Build & deploy](/docs/web/guides/deploy/) for the guided wizard and CI.

- **`load` and `generate` run at build only.** The browser never calls them. On client navigation it reads the JSON the build saved.
- **Import routes from `@moku-labs/web/browser`.** The client bundle imports the route file. A route file that imports `@moku-labs/web` drags Node code into the bundle and the build fails on a Node-only dependency.
- **`site.name` and `site.url` are required.** `createApp` throws `[web] site.name is required.` when they are missing, in the Node app and in the browser app.
- **`cli.build()` checks for `dist/404.html`.** Set `build.notFound`, or Cloudflare Pages treats the project as an SPA.

## Next

- [How it works](/docs/web/how-it-works/): what the build writes and what the browser does with it.
- [Routing](/docs/web/guides/routing/): patterns, builder methods, links.
- [Islands](/docs/web/guides/islands/): make parts of a page interactive.
- [Build & deploy](/docs/web/guides/deploy/): scripts, the dev server, Cloudflare Pages.


# How it works

Source: https://moku-labs.com/docs/web/how-it-works/ · @moku-labs/web@2.4.11

> One route, two places: the build renders HTML, the browser renders the saved data.

## The picture

*Diagram: Build to SPA*

1. **Build.** Node runs every route: `generate` lists the pages, `load` fetches the data, `head` and `render` turn it into HTML. The kernel checked the plugin list before anything ran.
2. **Static HTML.** Each URL is a finished `index.html`. It works with JavaScript off, and it is what search engines see.
3. **Hydration.** `app.start()` in the browser mounts the islands onto that HTML. Nothing else is re-rendered.
4. **Data navigation.** A link click matches the route, fetches the page JSON with `data.at(path)` and runs the same `render` with it.

## The same render runs in both places

A route is one object. The build and the browser read different parts of it.

| Handler | Build (Node) | Browser |
|---|---|---|
| `.generate(ctx)` | lists the param sets to pre-render | never |
| `.load(ctx)` | fetches the page data | never |
| `.render(ctx)` | renders the HTML | renders the swap region on navigation |
| `.head(ctx)` | composes `<head>` | the head is copied from the fetched page or re-titled |

In `spa` and `hybrid` mode the build saves what `load` returned next to the HTML, as JSON. The
browser fetches that file and passes it to `render` as `ctx.data`. There is no second
projection of the data and no second render function, so the HTML and the client view cannot
drift apart.

## Where the data comes from

```text
BUILD (mode !== "ssg")                 ON DISK                               CLIENT NAVIGATION
for each page of each route:           dist/hello-world/index.html           click /second-post/
  data = route.load(ctx)       ──►     (static HTML: SEO + first paint)      1. router.match(path)
  html = render(ctx) to string ──►                                           2. data.at(path) → fetch
  data.write([{ path, data }]) ──►     dist/_data/hello-world/index.json        /_data/second-post/index.json
                                       (the load() result, never HTML)       3. ctx.data = the JSON
                                                                             4. route.render(ctx) → swap
```

The sidecar of a list page holds what its `load` returned, for example slim cards. A detail page
holds one article. A route without `load` still gets an empty `{}` sidecar, so client navigation
to it never falls back.

```sh
$ ls dist dist/_data
dist:
404.html  _data  _headers  assets  atom.xml  en  feed.json  feed.xml
hello-world  index.html  robots.txt  second-post  sitemap.xml  uk

dist/_data:
en  hello-world  index.json  second-post  uk
$ cat dist/_data/index.json
[{"contentId":"en:0000:second-post","status":"published","title":"Second post",...}]
```

## Rendering modes

One global switch, `createApp({ config: { mode } })`, read by every plugin through
`router.mode()`.

| Mode | The build writes | The browser does | Use it for |
|---|---|---|---|
| `ssg` | HTML only | full page loads, or HTML-over-fetch when the `spa` plugin intercepts | docs, marketing, content sites |
| `spa` | HTML and JSON sidecars | data navigation: fetch JSON, render in place | app-like sites |
| `hybrid` | HTML and JSON sidecars | data navigation where a sidecar exists, else HTML-over-fetch | the default |

Data navigation needs the `data` plugin on both sides: in the Node app so the build writes the
sidecars, in the browser app so `spa` can read them. Without it, every navigation fetches the
next page's HTML and swaps the `main > section` region.

## Two apps, one route table

```ts
import { buildPlugin, contentPlugin, createApp, dataPlugin, fileSystemContent } from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, dataPlugin, buildPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    content: { providers: [fileSystemContent({ contentDir: "content" })] }
  }
});
```

1. The Node app imports the routes with their loaders.

```ts
import { createApp, dataPlugin } from "@moku-labs/web/browser";
import { routes } from "./routes";

const app = createApp({
  plugins: [dataPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes }
  }
});

await app.start();
```

1. The browser entry cannot pull in `node:fs`.
2. The same table. Its loaders ship but never run here.

A complete app on the browser entry, in one file. It compiles as it is:

```tsx
import { createApp, createIsland, defineRoutes, route } from "@moku-labs/web/browser";

const routes = defineRoutes({
  home: route("/").render(() => <h1>Home</h1>),
  about: route("/about/").render(() => <h1>About</h1>)
});

const clock = createIsland("clock", {
  onMount(ctx) {
    const timer = setInterval(() => {
      ctx.el.textContent = new Date().toLocaleTimeString();
    }, 1000);
    ctx.cleanup(() => clearInterval(timer));
  }
});

const app = createApp({
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "Demo", url: "https://demo.dev", author: "", description: "" },
    router: { routes },
    spa: { islands: [clock] }
  }
});

await app.start();
```

1. Runs when the island is destroyed, for example on navigation.

- **`load` runs at build only.** Do not expect it on navigation. The browser reads the JSON the build wrote.
- **No HTML in the JSON.** The route owns rendering, `data` owns transport. A missing or broken sidecar falls back to fetching the HTML, then to a full page load.
- **Use `@moku-labs/web/browser` for the client.** Its import graph has no Node module. Tree-shaking the root entry is not the same guarantee: bundling entries together can merge Node code into a shared chunk.
- **The layout is not re-applied on the client.** `.layout()` frames the page at build. On navigation the chrome stays and only the swap region changes.

## Related

- [Routing](/docs/web/guides/routing/): the route builder in full.
- [Data](/docs/web/guides/data/): the sidecars and the `data` plugin.
- [SPA navigation](/docs/web/guides/spa/): interception, transitions, scroll.
- [spa plugin](/docs/web/plugins/spa/): config, API, events.


# Routing

Source: https://moku-labs.com/docs/web/guides/routing/ · @moku-labs/web@2.4.11

> route().load().render().head(): one typed builder is the contract for the build and the browser.

## How routing works

A route is a URL pattern plus optional handlers. You write routes with `route()`, a plain function
that runs before `createApp`. You register them in one place, `pluginConfigs.router.routes`. The
router plugin compiles the table once, while `createApp` runs.

At build, the `build` plugin walks the table: it expands each route into concrete pages with
`generate`, loads their data, composes the head and renders the HTML. In the browser, `spa` matches
the URL against the same table and runs `render` again with the saved data.

- pattern
- **generate**
- **load**
- **head**
- **render**
- index.html

Types flow along the chain. `ctx.params` comes from the pattern, `ctx.data` from what `load`
returns. There is no codegen and no cast.

## Patterns

| Syntax | Meaning | Example |
|---|---|---|
| `{name}` | Required param | `/{slug}/` → `ctx.params.slug: string` |
| `{name:?}` | Optional param. `toUrl` drops the segment when it is missing. | `/archive/{page:?}/` → `ctx.params.page?: string` |
| `{lang:?}` | Locale slot. The default locale is served at bare paths. It does not count toward specificity. | `/{lang:?}/{slug}/` |

When two patterns match a URL, the one with fewer dynamic segments wins. On a tie the route
declared first wins. Matching uses a plain `RegExp`, so it works in every browser, including
those without `URLPattern`.

## Define routes

Three files: the route table, a component that builds links, and the app that registers the
table.

```tsx
import { contentPlugin, defineRoutes, route } from "@moku-labs/web/browser";
import type { Content } from "@moku-labs/web/browser";

function PostList(props: { cards: Content.ArticleCard[] }) {
  return (
    <ul>
      {props.cards.map(card => (
        <li key={card.contentId}>
          <a href={card.url}>{card.title}</a>
        </li>
      ))}
    </ul>
  );
}

export const routes = defineRoutes({
  home: route("/{lang:?}/")
    .generate(ctx => [{ lang: ctx.locale }])
    .load(async ctx => {
      const content = ctx.require(contentPlugin);
      const byLocale = await content.loadAll();
      return (byLocale.get(ctx.locale) ?? []).map(article => content.articleToCard(article));
    })
    .render(ctx => <PostList cards={ctx.data} />)
    .head(() => ({ title: "Home" })),
  post: route("/{lang:?}/{slug}/")
    .generate(async ctx => {
      const byLocale = await ctx.require(contentPlugin).loadAll();
      return (byLocale.get(ctx.locale) ?? []).map(article => ({
        lang: ctx.locale,
        slug: article.computed.slug
      }));
    })
    .load(ctx => ctx.require(contentPlugin).load(ctx.params.slug, ctx.locale))
    .render(ctx => <article dangerouslySetInnerHTML={{ __html: ctx.data.html }} />)
    .head(ctx => ({ title: ctx.data.frontmatter.title }))
    .meta({ section: "blog" })
});
```

1. `defineRoutes` keeps the literal type of each route for IntelliSense.
2. `generate` returns the param sets to pre-render, once per locale.
3. `load` gets `{ params, locale, require, has }`. Its return type is `ctx.data` below.
4. `meta` is a JSON bag, shipped to the browser in `clientManifest()`.

```tsx
import type { Content } from "@moku-labs/web/browser";

type Url = (name: string, params?: Record<string, string>) => string;

export function PostLink(props: { card: Content.ArticleCard; slug: string; url: Url }) {
  return (
    <a href={props.url("post", { slug: props.slug })}>
      <h2>{props.card.title}</h2>
      <time>{props.card.date}</time>
    </a>
  );
}
```

1. Inside `render` and `head`, `ctx.url(name, params)` builds links. Pass it down.

```ts
import { buildPlugin, contentPlugin, createApp, fileSystemContent } from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, buildPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
    content: { providers: [fileSystemContent({ contentDir: "content" })] }
  }
});
```

1. The render mode is global config, not router config.
2. The only way to register routes. An `import * as routes` namespace works too.

## Load data

A route without `load` is a static page: `ctx.data` is `unknown` and the build writes an empty
`{}` sidecar. Add `load` and `ctx.data` takes its return type, in `render` and in `head`.

```diff
 import { contentPlugin, defineRoutes, route } from "@moku-labs/web/browser";
 
 export const routes = defineRoutes({
   post: route("/{slug}/")
-    .render(ctx => <h1>{ctx.params.slug}</h1>)
-    .head(ctx => ({ title: ctx.params.slug }))
+    .load(ctx => ctx.require(contentPlugin).load(ctx.params.slug, ctx.locale))
+    .render(ctx => <h1>{ctx.data.frontmatter.title}</h1>)
+    .head(ctx => ({ title: ctx.data.frontmatter.title, description: ctx.data.frontmatter.description }))
 });
```

`load` may be async. It runs inside the build plugin, so `ctx.require` reaches any plugin in the
Node app, and `ctx.has(name)` tells you whether an optional one is there.

## Set the head

`.head(ctx)` returns the page's title, description and extra elements. The [head
plugin](/docs/web/plugins/head/) adds the title template, canonical, Open Graph, Twitter and
hreflang tags around it.

```tsx
import { defineRoutes, jsonLd, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  about: route("/about/")
    .render(() => <h1>About</h1>)
    .head(ctx => ({
      title: "About",
      description: "Who writes this blog.",
      image: "/og/about.png",
      elements: [jsonLd({ "@context": "https://schema.org", "@type": "AboutPage", url: ctx.url("about") })]
    }))
});
```

1. Becomes `<title>` through `head.titleTemplate`.
2. Relative images are made absolute against `site.url`.

## Dynamic paths

A route with a dynamic segment renders one page per param set that `generate` returns. The build
calls `generate` once per locale, default locale first. Two param sets that resolve to the same
file are written once.

| Route | `generate` | Pages written |
|---|---|---|
| `/{slug}/` | `[{ slug: "a" }, { slug: "b" }]` | `a/index.html`, `b/index.html` |
| `/{lang:?}/` with `en`, `uk` | `[{ lang: ctx.locale }]` | `index.html`, `en/index.html`, `uk/index.html` |
| `/{lang:?}/` with `en`, `uk` | none | `index.html` and `en/index.html` only |
| `/b/{id}/` in `mode: "spa"` | none | none: a client-only route, rendered in the browser from the URL |

`.toFile(params => path)` overrides where a page is written. The URL stays the pattern's URL.

## At build

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ bundle · 5ms
✓ content · 1239ms
✓ pages · 5ms
✓ sitemap · 1ms
✓ BUILD · 9 pages                                1252ms · ./dist/
$ find dist -name index.html | sort
dist/en/hello-world/index.html
dist/en/index.html
dist/en/second-post/index.html
dist/hello-world/index.html
dist/index.html
dist/second-post/index.html
dist/uk/hello-world/index.html
dist/uk/index.html
dist/uk/second-post/index.html
```

The English pages live at bare paths. The `/en/…` copies carry a canonical link to the bare URL,
so an explicit `/en/` link works without a redirect.

## Builder methods

| Method | Runs | What it does |
|---|---|---|
| `.generate(ctx => params[])` | build | Param sets to pre-render. `ctx = { locale, require, has }`. May be async. |
| `.load(ctx => D)` | build | Page data. `ctx = { params, locale, require, has }`. Widens `ctx.data` to `D`. May be async. |
| `.render(ctx => VNode)` | build and browser | The page. `ctx = { params, data, locale, meta, url }`. |
| `.head(ctx => HeadConfig)` | build and browser | `{ title?, description?, canonical?, image?, elements? }`. Same `ctx` as `render`. |
| `.layout((ctx, children) => VNode)` | build | Wraps the page in chrome. Not re-applied on client navigation. |
| `.meta(record)` | | A JSON-serializable bag, readable as `ctx.meta` in `render`, `head`, `layout` and islands. |
| `.transition(mode)` | browser | `"none"`, `"crossfade"`, `"slide"` or `"morph"` for navigations to this route. |
| `.scroll(mode)` | browser | `"top"` or `"preserve"` for navigations to this route. |
| `.toFile(params => path)` | build | Output file override. |
| `.toJson(ctx => unknown)` | | Stores a JSON serializer on the route. No built-in plugin reads it in 2.4.11. |

## Links

Inside `render` and `head`, `ctx.url(name, params)` builds a link. It gives the same result as
`app.router.toUrl`. Outside a route, in components and islands, use `createUrls`:

```ts
import { createUrls, defineRoutes, route } from "@moku-labs/web/browser";

const routes = defineRoutes({
  post: route("/{lang:?}/{slug}/")
});

export const urls = createUrls(routes, "en");

urls.toUrl("post", { lang: "en", slug: "hello" }); // "/hello/"
urls.toUrl("post", { lang: "uk", slug: "hello" }); // "/uk/hello/"
```

1. Pass the default locale. The helper is app-free and cannot read i18n.

Without the second argument every locale keeps its prefix: `"/en/hello/"`. `toUrl` only accepts
names from the map, and throws `[web] router: unknown route name "…".` on a name it does not know.

## RouterApi

Mounted at `app.router` and reachable with `ctx.require(routerPlugin)`.

| Method | Returns |
|---|---|
| `match(pathname)` | `{ params, route }` for the most specific match, or `null`. |
| `toUrl(routeName, params)` | The URL. Throws on an unknown name. |
| `entries()` | Every route as `{ pattern, name, meta, toUrl, toFile, match }`, most specific first. |
| `manifest()` | The full definitions with handlers, in declaration order. The build reads this. |
| `clientManifest()` | `{ pattern, name, meta }[]` with no functions, JSON-safe. |
| `mode()` | `"ssg"`, `"spa"` or `"hybrid"`, from the global config. |

- **`load` and `generate` never run in the browser.** The route file still ships to the client. Keep heavy Node-only code behind `ctx.require` in the loader, not in top-level imports of the route file.
- **There is no runtime registration.** `pluginConfigs.router.routes` is the only path. Without it every router call throws `[web] router: routes not registered.`
- **The mode is global.** Set `createApp({ config: { mode } })`. Router config has only `routes`.
- **A `{lang:?}` route without `generate` gets one page.** The build expands it for the default locale only. Return `[{ lang: ctx.locale }]` to get a page per locale.
- **Only `{lang:?}` matches without its segment.** `/archive/{page:?}/` matches `/archive/2/`, not `/archive/`. Declare a second route for the bare path.
- **Patterns start with `/`.** `route("about/")` fails `createApp` with `[web] router: route "about" pattern must start with "/" (got "about/").`

## Related

- [router plugin](/docs/web/plugins/router/): config, API, the matching model.
- [Head & SEO](/docs/web/guides/head/): what `.head()` turns into.
- [i18n](/docs/web/guides/i18n/): the `{lang:?}` slot and bare default-locale paths.
- [SPA navigation](/docs/web/guides/spa/): `.transition()` and `.scroll()` in action.


# Islands

Source: https://moku-labs.com/docs/web/guides/islands/ · @moku-labs/web@2.4.11

> createIsland: state, render, events and an API for the parts of a page that run in the browser.

## How islands work

An island is the part of a page that runs in the browser. The build renders the whole page to
HTML, islands included. In the browser, `app.start()` finds every element with
`data-island="name"` and mounts the island registered under that name onto it.

An island outside the swap region (`spa.swapSelector`, `main > section` by default) is
**persistent**: it survives navigation and hears `onNavStart` and `onNavEnd`. An island inside
the swap region is **page-specific**: it is destroyed and created again with the page.

`createIsland(name, spec)` takes a spec shaped like a plugin:

| Key | What it is |
|---|---|
| `state(ctx)` | Builds the per-element state once, at mount. |
| `render(state, ctx)` | Returns what the element shows. Runs after mount and after every `ctx.set`, batched. |
| `events` | `"event selector"` → handler. One delegated listener per event type, removed on destroy. |
| `api(ctx)` | A public API other islands reach with `ctx.island(name)`. |
| `onCreate` … `onDestroy` | Lifecycle hooks. |

Every key is optional. A spec with only hooks is fine.

## Example

```tsx
import { createIsland } from "@moku-labs/web/browser";

type LikeState = { count: number; liked: boolean };

export const likeButton = createIsland("like-button", {
  state: (ctx): LikeState => ({
    count: Number(ctx.el.getAttribute("data-count") ?? 0),
    liked: false
  }),
  render: state => (
    <button type="button" aria-pressed={state.liked}>
      Like {state.count}
    </button>
  ),
  events: {
    "click button": ctx =>
      ctx.set(previous => ({
        liked: !previous.liked,
        count: previous.count + (previous.liked ? -1 : 1)
      }))
  },
  api: ctx => ({ count: () => ctx.state.count })
});
```

1. The name matches `data-island="like-button"`. It must not be empty.
2. State is per element. Seed it from the server-rendered attributes.
3. `ctx.set` merges a patch, or an updater's result, and schedules one render.
4. Other islands read it with `ctx.island("like-button")`.

```tsx
export function PostFooter(props: { likes: number }) {
  return (
    <footer>
      <div data-island="like-button" data-count={String(props.likes)}>
        <button type="button">Like {props.likes}</button>
      </div>
    </footer>
  );
}
```

```ts
import { createApp } from "@moku-labs/web/browser";
import { site } from "./site";
import { likeButton } from "./islands/like-button";
import { routes } from "./routes";

const app = createApp({
  pluginConfigs: { site, router: { routes }, spa: { islands: [likeButton] } }
});

await app.start();
```

The static HTML already shows `Like 3`, so the page reads right with JavaScript off. On mount
the island renders over it and takes over the clicks.

## At build

Islands ship in the client bundle. The build bundles `build.clientEntry` (or the first of
`src/client/main.ts`, `src/client/main.tsx`, `src/main.ts`) and links it into every page.

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ bundle · 5ms
✓ pages · 5ms
✓ BUILD · 9 pages                                1252ms · ./dist/
$ ls dist/assets
chunk-9g7zwee8.js  chunk-a5gpvyg6.js  chunk-hm1r9zq7.js  chunk-ja8ap6vw.js
client-7wyejjw7.js  main-gzka1ns2.css
```

Every bundle file name carries a content hash, so the generated `_headers` can mark them
immutable.

## The island context

Every hook, `render`, `state`, event handler and `api` gets the same `ctx`.

| Member | What it is |
|---|---|
| `el` | The bound element. |
| `data` | Page data parsed from `script#__DATA__`, or `{}`. |
| `params`, `meta`, `locale` | The matched route's params, `.meta()` bag and locale. |
| `url(name, params?)` | A link, same output as `app.router.toUrl`. |
| `navigate(path, options?)` | SPA navigation, no `app` needed. `options = { scroll?, replace? }`. |
| `state` | The live state. `undefined` for a hooks-only island. |
| `set(patch)` | Merge a patch, or `prev => patch`, and schedule one render. |
| `flush()` | Render now. Mostly for tests. |
| `cleanup(dispose)` | Run on destroy, last in first out: timers, subscriptions, global listeners. |
| `island<T>(name)` | Another island's `api`, or `undefined`. |

## Lifecycle hooks

| Hook | When |
|---|---|
| `onCreate` | Once, before the instance attaches. |
| `onMount` | After it attaches. May be async. |
| `onNavStart` | A navigation begins while it is mounted. |
| `onNavEnd` | A navigation finished. Persistent islands only. |
| `onUnMount` | Before it detaches. |
| `onDestroy` | Once, after it detaches. |

A hooks-only island that marks navigation state on a persistent element:

```ts
import { createIsland } from "@moku-labs/web/browser";

export const navState = createIsland("nav-state", {
  onNavStart({ el }) {
    el.setAttribute("data-loading", "");
  },
  onNavEnd({ el }) {
    el.removeAttribute("data-loading");
  }
});
```

## Talk to another island

```tsx
import { createIsland } from "@moku-labs/web/browser";

type LikeApi = { count: () => number };

export const share = createIsland("share", {
  state: () => ({ text: "Share" }),
  render: state => <button type="button">{state.text}</button>,
  events: {
    "click button": ctx => {
      const likes = ctx.island<LikeApi>("like-button")?.count() ?? 0;
      ctx.set({ text: `Share (${likes} likes)` });
    }
  }
});
```

1. `undefined` when no `like-button` island is registered.

## Realtime channels

`createChannel` is a self-healing WebSocket for islands that consume a server push stream, such
as a Durable Object from `@moku-labs/worker`. It reconnects with backoff, can send a keepalive,
buffers frames until you `seed`, and counts subscribers: the first connects, the last
disconnects.

```ts
import { createChannel, createIsland } from "@moku-labs/web/browser";

type BoardPatch = { type: "card.moved"; cardId: string; to: string };

const board = createChannel<BoardPatch>({
  url: id => `${location.origin.replace(/^http/, "ws")}/ws/board/${id}`,
  keepAlive: { send: "ping", ignore: "pong" },
  bufferUntilSeed: true
});

export const boardIsland = createIsland("board", {
  state: () => ({ moves: 0 }),
  render: state => `<p>${state.moves} moves</p>`,
  onMount(ctx) {
    const boardId = ctx.params.id ?? "";
    const off = board.subscribe(boardId, () => ctx.set(previous => ({ moves: previous.moves + 1 })));
    ctx.cleanup(off);
    board.seed(boardId);
  }
});
```

1. Frames that arrive before `seed` are queued, so the connect-then-load race drops nothing.

## Test an island

`@moku-labs/web/testing` mounts one island through the real spa internals, with no `createApp`,
router or network. The test runner needs a DOM (happy-dom or jsdom).

```ts
import { createIsland } from "@moku-labs/web/browser";
import { mountIsland } from "@moku-labs/web/testing";
import { expect, it } from "vitest";

const counter = createIsland("counter", {
  state: () => ({ count: 0 }),
  render: state => `<button type="button">${state.count}</button>`,
  events: { "click button": ctx => ctx.set(previous => ({ count: previous.count + 1 })) }
});

it("counts clicks", () => {
  const island = mountIsland<{ count: number }>(counter);
  island.flush();
  island.fire("click button");
  island.flush();
  expect(island.el.textContent).toBe("1");
});
```

1. Same `"event selector"` grammar as the `events` map.

`renderIsland(render, { state })` renders only the `render` function, for the cheapest view
tests. An island that returns JSX needs `await island.settle()` first, which loads the lazy
Preact render chunk.

- **There is no `createComponent` in 2.4.11.** The `state`, `render`, `events` and `api` spec lives on `createIsland`.
- **`render` replaces the server markup on mount.** Render the same markup the server rendered, or the element jumps.
- **Return `null` for an empty island.** It unmounts the Preact tree and stays mountable. Returning `""` corrupts Preact's tree and the island never renders again.
- **`ctx.data` reads `script#__DATA__`.** The build does not write that script. Render it in your page when an island needs page data, or read `data-*` attributes.
- **A duplicate name replaces the first island.** `register` logs `spa:island-collision` and the last one wins.
- **A typo in a hook name throws.** `onMout` fails `createIsland` with `[web] unknown island hook "onMout" on "x"` and the list of valid hooks.

## Related

- [spa plugin](/docs/web/plugins/spa/): `islands`, `swapSelector`, the API at `app.spa`.
- [SPA navigation](/docs/web/guides/spa/): what happens to islands on a link click.
- [API reference](/docs/web/api/): `createIsland`, `createChannel`, `lazyEmbed`.


# Content & collections

Source: https://moku-labs.com/docs/web/guides/content/ · @moku-labs/web@2.4.11

> Markdown articles with locale fallback, and sharded JSON collections read on demand.

## How content works

The `content` plugin turns Markdown files into `Article` objects. It does not read files itself:
a **provider** does. On Node you compose `fileSystemContent`, which reads
`content/<slug>/<locale>.md`, parses the frontmatter and renders the body to HTML with Shiki
highlighting. The plugin adds locale fallback, draft filtering, date sorting and a cache on top.

Routes reach it in build-only loaders with `ctx.require(contentPlugin)`. Nothing of the Markdown
pipeline ships to the browser.

| `Article` field | Holds |
|---|---|
| `frontmatter` | `title`, `date`, `description`, `tags`, `language`, `draft?`, `author?` |
| `computed` | `slug`, `readingTime` (minutes, at least 1), `contentId`, `status`, `wordCount` |
| `html` | The rendered body |
| `locale`, `isFallback` | The requested locale, and whether the default-locale file was used |
| `url` | The article URL in this locale, e.g. `/uk/second-post/` |

For data that is not an article and that the browser loads on demand, such as a search index,
the `collection` plugin writes JSON shards at build and reads them in the browser.

## Example

```text
content/
  hello-world/
    en.md          # frontmatter: title, date, description, tags, language
    uk.md          # same slug, another locale
    images/
      cover.png    # co-located, copied to dist/hello-world/images/
  second-post/
    en.md          # no uk.md: /uk/second-post/ falls back to English
```

```ts
import { buildPlugin, contentPlugin, createApp, fileSystemContent } from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, buildPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    content: {
      providers: [
        fileSystemContent({
          contentDir: "content",
          shikiTheme: "github-dark",
          defaultAuthor: "Ada"
        })
      ]
    },
    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
    router: { routes }
  }
});
```

1. A bundled Shiki theme name, or your own theme object.
2. Used when an article's frontmatter has no `author`.

```tsx
import { contentPlugin, defineRoutes, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  post: route("/{lang:?}/{slug}/")
    .generate(async ctx => {
      const byLocale = await ctx.require(contentPlugin).loadAll();
      return (byLocale.get(ctx.locale) ?? []).map(article => ({
        lang: ctx.locale,
        slug: article.computed.slug
      }));
    })
    .load(ctx => ctx.require(contentPlugin).load(ctx.params.slug, ctx.locale))
    .render(ctx => (
      <article>
        {ctx.data.isFallback ? <p>This post is not translated yet.</p> : null}
        <h1>{ctx.data.frontmatter.title}</h1>
        <div dangerouslySetInnerHTML={{ __html: ctx.data.html }} />
      </article>
    ))
    .head(ctx => ({ title: ctx.data.frontmatter.title, description: ctx.data.frontmatter.description }))
});
```

1. Cached: every page of every route can call it, the files are read once.

## Locale fallback and drafts

`load(slug, locale)` reads `<slug>/<locale>.md`. When that file is missing it reads the default
locale's file and sets `isFallback: true`. `locale` and `url` stay the requested locale, so the
page is written at `/uk/second-post/`. `loadAll()` does the same for every slug and every
locale, then sorts each locale's list by date, newest first.

An article with `draft: true` is left out when the global `stage` is `"production"`, the
default. In `"development"` and `"test"` it loads normally. In production a draft passed to
`load()` throws the same not-found error as a missing file, so drafts cannot be probed.

## The Markdown pipeline

The framework pipeline already includes GitHub-flavoured Markdown, the generic directive syntax,
Shiki and, last, `rehype-sanitize`.

| Option of `fileSystemContent` | Default | What it does |
|---|---|---|
| `contentDir` | required | The article root. |
| `trustedContent` | `false` | `false` runs `rehype-sanitize` as the last step. Set `true` only when you write every file yourself. |
| `shikiTheme` | `"github-dark"` | A bundled theme name or a `ThemeRegistration` object. |
| `defaultAuthor` | none | Author for articles without one. |
| `extraRemarkPlugins` | `[]` | Added after the framework's remark plugins. They never replace them. |
| `extraRehypePlugins` | `[]` | Added after the framework transforms, before Shiki and sanitize. |
| `mermaid` | off | Renders `mermaid` fences to inline SVG at build. Needs `trustedContent` and the optional peer `mermaid-isomorphic`. |
| `embed` | off | `::embed{src="…" title="…"}` becomes a click-to-load iframe facade. Needs `trustedContent`. |
| `gallery` | off | `::gallery{src="./images/dir/" caption="…"}` becomes an image set from a co-located folder. Needs `trustedContent`. |

`::embed` needs the `lazyEmbed` island in the browser to swap the facade for the real iframe:

```tsx
import { createApp, defineRoutes, lazyEmbed, route } from "@moku-labs/web/browser";

const routes = defineRoutes({ home: route("/").render(() => <h1>My Blog</h1>) });

const app = createApp({
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    spa: { islands: [lazyEmbed] }
  }
});

await app.start();
```

1. Activates every `[data-island="lazy-embed"]` facade on click.

## Collections

A collection is a set of JSON files the build writes and the browser reads on demand. You name
the collection and the shard; the plugin owns the file layout:
`<outDir>/<collection>/<shard>.json`, fetched from `<baseUrl><collection>/<shard>.json`.

```ts
import { collectionPlugin, contentPlugin, createApp, fileSystemContent } from "@moku-labs/web";

const app = createApp({
  plugins: [contentPlugin, collectionPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
    content: { providers: [fileSystemContent({ contentDir: "content" })] }
  }
});

const byLocale = await app.content.loadAll();
const shards = [...byLocale].map(([locale, articles]) => ({
  collection: "search",
  shard: locale,
  data: articles.map(article => app.content.articleToCard(article))
}));

const summary = await app.collection.write(shards, { outDir: "dist" });
console.log(summary.files);
```

1. A shard key may contain `/`, e.g. `"en/animals"`, which becomes a folder.

```ts
import { loadCollectionShard } from "@moku-labs/web/browser";
import type { Content } from "@moku-labs/web/browser";

export async function searchTitles(query: string): Promise<Content.ArticleCard[]> {
  const cards = await loadCollectionShard<Content.ArticleCard[]>("/", "search", "en");
  const needle = query.toLowerCase();
  return cards.filter(card => card.title.toLowerCase().includes(needle));
}
```

1. Fetches `/search/en.json` and throws on a non-OK response.

```sh
$ bun scripts/write-index.ts
[ "search/en.json", "search/uk.json" ]
$ head -c 120 dist/search/uk.json
[{"contentId":"uk:0000:second-post","status":"published","title":"Second post","date":"2026-02-01",
```

`collectionPlugin` is exported from `@moku-labs/web` only. In the browser bundle, read shards
with `loadCollectionShard` or build the URL with `collectionUrl` from `@moku-labs/web/browser`.

- **`content` needs a provider.** The default `providers: []` fails `createApp` with `[web] content: no provider composed.`
- **Five frontmatter fields are required.** `title`, `date`, `description`, `tags` and `language`. A missing one fails the build with the field name.
- **`load()` throws on a missing article.** `[web] content article "nope" not found for locale "en".` Build page lists from `loadAll()`, not from guessed slugs.
- **`loadAll()` returns a cached object.** Copy before you sort or change it.
- **`trustedContent: false` strips more than scripts.** Inline `style` and Shiki's per-token colours go too. Use `true` only for Markdown you write yourself.
- **Write collections after the build.** `build.run()` cleans `outDir` first, so a shard written before it is deleted.

## Related

- [content plugin](/docs/web/plugins/content/): the full API and every option.
- [collection plugin](/docs/web/plugins/collection/): `write`, `at`, `urlFor`, `fileFor`.
- [Routing](/docs/web/guides/routing/): `generate` and `load` with `ctx.require`.
- [i18n](/docs/web/guides/i18n/): locales and the fallback chain.


# Head & SEO

Source: https://moku-labs.com/docs/web/guides/head/ · @moku-labs/web@2.4.11

> Title, canonical, Open Graph, Twitter, JSON-LD, hreflang, feeds, sitemap and OG images.

## How the head works

Each route's `.head(ctx)` returns a small object: `title`, `description`, `canonical`, `image`
and extra `elements`. The `head` plugin composes the full `<head>` from it, in this order:

1. **Title.** `head.titleTemplate` with `%s` replaced by the route title, or the site name.
2. **Description.** The route description, or `site.description`.
3. **Open Graph and Twitter.** Title, description, URL, and `og:image` / `twitter:image` from the route `image` or `head.defaultOgImage`, made absolute against `site.url`. `og:locale` when `i18n.ogLocaleMap` has the page locale.
4. **Canonical.** The route `canonical`, or `site.url` joined with the page URL.
5. **hreflang.** One alternate link per locale, plus `x-default`.
6. **Your elements.** The route `elements`, last. An element with the same key as a generated one replaces it.

The build writes this into every page. On client navigation `spa` copies the head from the
fetched page, or sets the title through `head.composeTitle` on the data path. A head element is
a plain object, not a Preact node, so the same descriptors serialize at build and apply in the
browser.

The `build` plugin adds the site-wide files: feeds, `sitemap.xml`, `robots.txt` and OG images.

## Example

```ts
import { buildPlugin, contentPlugin, createApp, fileSystemContent } from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, buildPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    head: {
      titleTemplate: "%s · My Blog",
      defaultOgImage: "/og-default.png",
      twitterCard: "summary_large_image",
      twitterHandle: "@moku_labs"
    },
    i18n: { locales: ["en", "uk"], defaultLocale: "en", ogLocaleMap: { en: "en_US", uk: "uk_UA" } },
    router: { routes },
    content: { providers: [fileSystemContent({ contentDir: "content" })] }
  }
});
```

1. Must contain `%s`, or `createApp` throws.

```tsx
import { buildArticleHead, contentPlugin, defineRoutes, feedLink, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  post: route("/{slug}/")
    .load(ctx => ctx.require(contentPlugin).load(ctx.params.slug, ctx.locale))
    .render(ctx => <article dangerouslySetInnerHTML={{ __html: ctx.data.html }} />)
    .head(ctx => ({
      title: ctx.data.frontmatter.title,
      description: ctx.data.frontmatter.description,
      image: `/og/${ctx.data.computed.slug}.png`,
      elements: [
        ...buildArticleHead(
          {
            title: ctx.data.frontmatter.title,
            author: ctx.data.frontmatter.author ?? "Ada",
            published: ctx.data.frontmatter.date,
            tags: ctx.data.frontmatter.tags
          },
          `https://blog.dev${ctx.data.url}`
        ),
        feedLink("My Blog", "/feed.xml")
      ]
    }))
});
```

1. Relative is fine here: the head plugin makes it absolute.
2. Canonical, `og:type=article`, published time, author, tags and an Article JSON-LD block.

## What the build writes

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ pages · 5ms
✓ feeds · 2ms
✓ sitemap · 1ms
✓ BUILD · 9 pages                                1252ms · ./dist/
$ cat dist/robots.txt
User-agent: *
Allow: /
Sitemap: https://blog.dev/sitemap.xml
```

The head of `/uk/hello-world/`, as the build wrote it (one tag per line here):

```html
<title>Привіт, світ · My Blog</title>
<meta name="description" content="Перший допис.">
<meta property="og:title" content="Привіт, світ">
<meta property="og:description" content="Перший допис.">
<meta property="og:url" content="https://blog.dev/uk/hello-world/">
<meta name="twitter:card" content="summary_large_image">
<link rel="canonical" href="https://blog.dev/uk/hello-world/">
<link rel="alternate" hreflang="en" href="https://blog.dev/hello-world/">
<link rel="alternate" hreflang="uk" href="https://blog.dev/uk/hello-world/">
<link rel="alternate" hreflang="x-default" href="https://blog.dev/hello-world/">
<meta name="build-id" content="1793577742510-06dbe81d-2692-4613-a480-605d41931010">
<link rel="stylesheet" href="/assets/main-gzka1ns2.css">
<script type="module" src="/assets/client-7wyejjw7.js"></script>
```

The `build-id` meta and the asset tags are added by the build, after the head plugin. The sitemap lists the canonical URLs
only, so the `/en/…` copies of default-locale pages are not in it.

## Head helpers

Plain functions that return head elements. Use them in `elements`. Each one is exported from
both entries.

| Helper | Signature | Emits |
|---|---|---|
| `meta` | `meta(name, content)` | `<meta name content>`, key `meta:<name>` |
| `og` | `og(property, content)` | `<meta property content>`, key `meta:<property>` |
| `twitter` | `twitter(name, content)` | `<meta name content>`, key `meta:<name>` |
| `jsonLd` | `jsonLd(data)` | `<script type="application/ld+json">`, with `<`, `>` and `&` escaped |
| `canonical` | `canonical(url)` | `<link rel="canonical">`, key `link:canonical` |
| `hreflang` | `hreflang(locale, url)` | `<link rel="alternate" hreflang>`, key `link:alternate:<locale>` |
| `feedLink` | `feedLink(title, url, type?)` | `<link rel="alternate">`, RSS by default |
| `buildArticleHead` | `buildArticleHead(meta, canonicalUrl)` | The article set: canonical, `og:type`, `article:*` tags, JSON-LD |

To override a generated tag, return an element with the same key. `og("og:title", "Shorter")`
replaces the generated `og:title`.

## Site-wide outputs

```ts
pluginConfigs: {
  head: { defaultOgImage: "/og-default.png" },
  build: {
    feeds: true,
    sitemap: true,
    ogImage: { fontDir: "fonts", defaultCard: true }
  }
}
```

1. Points every page without its own image at the card the build renders.
2. `feed.xml`, `atom.xml` and `feed.json` from the content articles.
3. `sitemap.xml` and `robots.txt`.
4. One card per article in `og/<slug>.png`, plus `og-default.png`.

`ogImage` renders with Satori and needs a folder with at least one `.ttf`, `.otf` or `.woff`
font. `defaultCard` also takes a function `(input) => VNode` to draw your own site card. A card
is rendered again only when its article's title, the template or the size changed.

- **`titleTemplate` needs `%s`.** Without it `createApp` throws `[web] head: titleTemplate must contain the "%s" token (replaced by the route title), received "My Blog".`
- **`site.url` must be the production origin.** Canonical, `og:url`, relative images, the sitemap and the feeds are all built from it.
- **`buildArticleHead` does not resolve relative images.** Its `image` goes to `og:image` as you pass it. Pass an absolute URL.
- **`og:locale` needs `ogLocaleMap`.** Without a mapping for the page locale the tag is left out.
- **`ogImage.fontDir` is checked at `createApp`.** A missing folder, or one with no font file, fails before the build starts.

## Related

- [head plugin](/docs/web/plugins/head/): config, `render`, `siteHead`, `composeTitle`.
- [build plugin](/docs/web/plugins/build/): `feeds`, `sitemap`, `ogImage` and the other outputs.
- [i18n](/docs/web/guides/i18n/): hreflang and `og:locale`.


# i18n

Source: https://moku-labs.com/docs/web/guides/i18n/ · @moku-labs/web@2.4.11

> Locales, translations, and the default locale at bare paths.

## How i18n works

The `i18n` plugin is plain data: the locale list, the default locale, display names, an
`og:locale` map and a flat translation table. It has no state and no events. The other plugins
read it:

- **router** builds the `{lang:?}` matcher from the locale list. The default locale is served at
  bare paths, every other locale under its prefix.
- **build** calls `generate` once per locale, default first, and writes `<html lang>` per page.
- **content** reads `<slug>/<locale>.md` and falls back to the default locale's file.
- **head** writes one hreflang alternate per locale, an `x-default`, and `og:locale` when the map
  has the locale.

`t(locale, key)` never returns `undefined`: the requested locale, then the default locale, then
the key itself.

## Example

```ts
export const i18n = {
  locales: ["en", "uk"],
  defaultLocale: "en",
  localeNames: { en: "English", uk: "Українська" },
  ogLocaleMap: { en: "en_US", uk: "uk_UA" },
  translations: {
    en: { "nav.home": "Home", "nav.about": "About" },
    uk: { "nav.home": "Головна" }
  }
};
```

1. Priority order. Must not be empty.
2. Must be one of `locales`, or `createApp` throws.

```tsx
import { defineRoutes, i18nPlugin, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  home: route("/{lang:?}/")
    .generate(ctx => [{ lang: ctx.locale }])
    .load(ctx => {
      const i18n = ctx.require(i18nPlugin);
      return { home: i18n.t(ctx.locale, "nav.home"), about: i18n.t(ctx.locale, "nav.about") };
    })
    .render(ctx => (
      <nav>
        <a href={ctx.url("home", { lang: ctx.locale })}>{ctx.data.home}</a>
        <span>{ctx.data.about}</span>
      </nav>
    ))
    .head(ctx => ({ title: ctx.data.home }))
});
```

1. One page per locale: `/`, `/en/` and `/uk/`.
2. Translate in `load`: the strings land in the JSON sidecar, so client navigation renders the same words.

```ts
import { buildPlugin, createApp } from "@moku-labs/web";
import { routes } from "./routes";
import { i18n } from "./site";

export const app = createApp({
  plugins: [buildPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    i18n,
    router: { routes }
  }
});
```

On `/uk/` the page reads `Головна` and `About`: the Ukrainian table has no `nav.about`, so it falls
back to English.

## URLs

| Locale | URL | Also written |
|---|---|---|
| `en` (default) | `/hello-world/` | `/en/hello-world/`, a copy with a canonical link to the bare URL |
| `uk` | `/uk/hello-world/` | none |
| `uk`, no `uk.md` | `/uk/second-post/` | none. The page shows the English text with `isFallback: true` |

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ content · 1239ms
✓ pages · 5ms
✓ BUILD · 9 pages                                1252ms · ./dist/
$ ls dist/uk dist/en
dist/en:
hello-world  index.html  second-post

dist/uk:
hello-world  index.html  second-post
$ head -c 40 dist/uk/hello-world/index.html
<!DOCTYPE html><html lang="uk"><head>
```

## Links between locales

`ctx.url` and `app.router.toUrl` know the default locale. `createUrls` is app-free, so pass it
the default locale yourself. A language switcher replaces the history entry, so Back does not
step through the same page in another language:

```ts
import { createIsland } from "@moku-labs/web/browser";

export const languageSwitch = createIsland("language-switch", {
  events: {
    "click [data-locale]": (ctx, _event, target) => {
      const locale = target.getAttribute("data-locale") ?? "en";
      const name = target.getAttribute("data-route") ?? "home";
      const params: Record<string, string> = { lang: locale };
      for (const [key, value] of Object.entries(ctx.params)) {
        if (key !== "lang" && value !== undefined) params[key] = value;
      }
      ctx.navigate(ctx.url(name, params), { replace: true });
    }
  }
});
```

1. Keep the other params of the current page, such as `slug`.
2. `replace: true` swaps the current history entry instead of adding one.

- **`defaultLocale` must be in `locales`.** Otherwise `createApp` throws `[web] i18n.defaultLocale "en" is not in i18n.locales [uk].`
- **A `{lang:?}` route needs `generate` for every locale.** Without it the build writes the default locale only.
- **The default locale has no prefix.** `/hello/` is English and `/uk/hello/` is Ukrainian. The `/en/hello/` copy exists so explicit links work, and the sitemap leaves it out.
- **Show a notice on fallback pages.** `article.isFallback` is `true` when the text is the default locale's. The hreflang links still list every locale.
- **`render` has no `require`.** Read translations in `load` and pass them through `ctx.data`, or import your table in the component.

## Related

- [i18n plugin](/docs/web/plugins/i18n/): config and the `app.i18n` API.
- [Routing](/docs/web/guides/routing/): the `{lang:?}` slot and specificity.
- [Content & collections](/docs/web/guides/content/): locale files and fallback.
- [Head & SEO](/docs/web/guides/head/): hreflang and `og:locale`.


# Data

Source: https://moku-labs.com/docs/web/guides/data/ · @moku-labs/web@2.4.11

> SSG to DATA to SPA: the build saves each page's load() result, the browser fetches it.

## How data works

In `spa` and `hybrid` mode, with the `data` plugin composed, the build saves what each page's
`load` returned as a JSON file next to the HTML. On a link click, `spa` matches the route,
fetches that file with `data.at(path)` and runs the route's own `render` with it as `ctx.data`.

The payload follows `load`. A list page stores the slim cards its `load` returned. A detail page
stores one record. There is no second data shape to maintain, and no HTML in the JSON.

- load(ctx)
- data.write
- _data/…/index.json
- data.at(path)
- render(ctx)

`data` is not a default plugin. Compose it on both sides: in the Node app so the build writes the
files, and in the browser app so `spa` reads them. It has no dependencies and its Node writer is
loaded lazily, so the browser bundle stays free of `node:*`.

## Example

```tsx
import { contentPlugin, defineRoutes, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  home: route("/")
    .load(async ctx => {
      const content = ctx.require(contentPlugin);
      const articles = (await content.loadAll()).get(ctx.locale) ?? [];
      return articles.map(article => content.articleToCard(article));
    })
    .render(ctx => (
      <ul>
        {ctx.data.map(card => (
          <li key={card.contentId}>
            <a href={card.url}>{card.title}</a> · {card.readingTime} min
          </li>
        ))}
      </ul>
    ))
});
```

1. Return only what `render` needs. This array is the whole sidecar.

```ts
import { buildPlugin, contentPlugin, createApp, dataPlugin, fileSystemContent } from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, dataPlugin, buildPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    content: { providers: [fileSystemContent({ contentDir: "content" })] }
  }
});
```

1. Node side: the build writes one sidecar per rendered page.

```ts
import { createApp, dataPlugin } from "@moku-labs/web/browser";
import { routes } from "./routes";

const app = createApp({
  plugins: [dataPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes }
  }
});

await app.start();
```

1. Browser side: `spa` finds it with `ctx.has("data")` and fetches sidecars on navigation.

## At build

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ pages · 5ms
✓ BUILD · 9 pages                                1252ms · ./dist/
$ find dist/_data -name index.json | sort
dist/_data/en/hello-world/index.json
dist/_data/en/index.json
dist/_data/en/second-post/index.json
dist/_data/hello-world/index.json
dist/_data/index.json
dist/_data/second-post/index.json
dist/_data/uk/hello-world/index.json
dist/_data/uk/index.json
dist/_data/uk/second-post/index.json
$ cat dist/_data/index.json
[{"contentId":"en:0000:second-post","status":"published","title":"Second post","date":"2026-02-01","description":"Another one.","tags":[],"readingTime":1,"url":"/second-post/"},…]
```

One sidecar per rendered page, including the `/en/…` copies. A page whose route has no `load`
gets `{}`.

## The URL convention

`urlFor` and `fileFor` come from one function, so the file the build writes is exactly the URL
the browser fetches.

| Page path | `fileFor(path)` | `urlFor(path)` |
|---|---|---|
| `/` | `_data/index.json` | `/_data/index.json` |
| `/en/hello/` | `_data/en/hello/index.json` | `/_data/en/hello/index.json` |
| `/en/hello` | `_data/en/hello/index.json` | `/_data/en/hello/index.json` |

`outputDir` (default `"_data"`) is the folder under the build `outDir`. `baseUrl` (default
`"/_data/"`) is the URL the browser fetches from. Keep them in step.

## Read data yourself

`app.data.at(path)` fetches and caches a sidecar. It returns `unknown`, or `null` when the fetch
or the JSON parse fails.

```tsx
import { createApp, dataPlugin, defineRoutes, route } from "@moku-labs/web/browser";

const routes = defineRoutes({ home: route("/").render(() => <h1>Home</h1>) });

const app = createApp({
  plugins: [dataPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes }
  }
});

const url = app.data.urlFor("/second-post/"); // "/_data/second-post/index.json"
const page = await app.data.at("/second-post/");
console.log(url, page === null ? "no sidecar" : "ready");
```

1. Cached after the first fetch. A later navigation to the page reuses it.

- **`ssg` mode writes no sidecars.** Set `config.mode` to `"spa"` or `"hybrid"` on both apps.
- **Compose `data` on both sides.** Node only: the files exist but are never read. Browser only: every fetch fails and navigation falls back to HTML.
- **`render` must be a function of `ctx.data`, `ctx.params` and `ctx.locale`.** On the client nothing else is there. A render that reads module state shows different output after navigation.
- **There is no validation step.** The fetched JSON is `ctx.data` as it is. A missing or broken file falls back to HTML-over-fetch, then to a full page load.
- **`baseUrl` must start with `/`.** Otherwise `createApp` throws `[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`

## Related

- [data plugin](/docs/web/plugins/data/): config and the `app.data` API.
- [How it works](/docs/web/how-it-works/): where the data comes from.
- [SPA navigation](/docs/web/guides/spa/): what happens on a link click.


# SPA navigation

Source: https://moku-labs.com/docs/web/guides/spa/ · @moku-labs/web@2.4.11

> Intercepted links, region swaps, view transitions, scroll and programmatic navigation.

## How navigation works

After `app.start()` in the browser, the `spa` plugin intercepts same-origin link clicks. It
leaves alone clicks with a modifier key, links with `target="_blank"`, other origins and static
files such as `.xml`, `.json`, images, fonts and PDFs. It uses the Navigation API where the
browser has it, and the History API otherwise.

Every navigation takes the first path that works:

1. **Data path.** When `router.mode()` is not `"ssg"` and the `data` plugin is composed: match the route, fetch the page JSON, run the route's `render` into the swap region, re-mount the islands, set the title.
2. **HTML-over-fetch.** Fetch the next page's HTML, replace the `swapSelector` region, copy the head from the fetched document.
3. **Full page load.** When the fetch fails, the browser loads the URL normally.

Only the swap region changes: `main > section` by default. The header, the footer and the
persistent islands stay. A thin progress bar shows after 150 ms, so fast navigations show
nothing. Back and forward restore the scroll position saved for that page.

## Per-route transitions and scroll

The app sets the default on the `spa` plugin. A route overrides it for navigations to that
route.

```tsx
import { defineRoutes, route } from "@moku-labs/web/browser";

export const routes = defineRoutes({
  board: route("/board/{id}/")
    .render(ctx => <section data-board={ctx.params.id} />)
    .transition("slide"),
  issue: route("/board/{id}/issue/{issueId}/")
    .render(ctx => <section data-issue={ctx.params.issueId} />)
    .transition("morph")
    .scroll("preserve")
});
```

1. Navigations to a board slide. The swap is tagged so CSS can target it.
2. A shared `view-transition-name` morphs the card into the panel.
3. An overlay route: the board behind it does not move.

```ts
import { createApp } from "@moku-labs/web/browser";
import { routes } from "./routes";
import { site } from "./site";

const app = createApp({
  config: { mode: "spa" },
  pluginConfigs: { site, router: { routes }, spa: { viewTransitions: "crossfade", scrollRestoration: "top" } }
});

await app.start();
```

```css
:root[data-view-transition~="slide"]::view-transition-old(root) {
  animation: slide-out 200ms ease-in;
}

:root[data-view-transition~="slide"]::view-transition-new(root) {
  animation: slide-in 200ms ease-out;
}
```

`viewTransitions` takes `true` (crossfade), `false` (no transition) or a mode: `"none"`,
`"crossfade"`, `"slide"`, `"morph"`. A named mode is set on `:root` as `data-view-transition` and
as a view transition type, for `:active-view-transition-type(slide)`. Under
`prefers-reduced-motion` and in browsers without View Transitions the swap is instant.

## Navigate from code

| Caller | Call |
|---|---|
| An island | `ctx.navigate(path, { scroll?, replace? })` |
| Code with the app | `app.spa.navigate(path, options)` |
| Module scope, no app or island | `navigate(path, options)` from `@moku-labs/web/browser` |
| Leave the SPA on purpose | `app.spa.hardNavigate(url)` or `hardNavigate(url)` |

```ts
import { createUrls, defineRoutes, hardNavigate, navigate, route } from "@moku-labs/web/browser";

const routes = defineRoutes({
  board: route("/board/{id}/"),
  signin: route("/signin/")
});

const urls = createUrls(routes);

export function openBoard(id: string): void {
  navigate(urls.toUrl("board", { id }));
}

export function signOut(): void {
  hardNavigate(urls.toUrl("signin"));
}
```

1. The same swap pipeline as a link click. A no-op before `app.start()`.
2. A real page load. The sign-in page has another layout, so it cannot be swapped in.

`replace: true` swaps the current history entry instead of adding one, so Back skips the page you
came from.

## Listen to navigation

`spa` emits four events. A plugin in the browser app hooks them.

| Event | Payload | When |
|---|---|---|
| `spa:navigate` | `{ from: string; to: string }` | A navigation was intercepted and starts. |
| `spa:navigated` | `{ url: string }` | The swap finished and the new URL is active. |
| `spa:island-mount` | `{ name: string; el: Element }` | An island attached to an element. |
| `spa:island-unmount` | `{ name: string; el: Element }` | An island detached. |

```ts
import { createPlugin, spaPlugin } from "@moku-labs/web/browser";

export const analyticsPlugin = createPlugin("analytics", {
  depends: [spaPlugin],
  createState: (): { views: string[] } => ({ views: [] }),
  hooks: ctx => ({
    "spa:navigated": ({ url }) => {
      ctx.state.views.push(url);
      ctx.log.info("analytics:view", { url });
    }
  }),
  api: ctx => ({ views: () => [...ctx.state.views] })
});
```

1. Depending on `spa` makes its events visible to `hooks`, with typed payloads.

## Try it locally

`bun run dev` builds once, serves `dist/` with live reload and rebuilds on change. Navigation in
the dev server goes through the same SPA runtime as production.

```sh
$ bun run dev
▟▙ moku web  serve · dev                                 v2.4.11
✓ pages · 5ms
✓ BUILD · 9 pages                                1252ms · ./dist/
➜ Local    http://localhost:4173
➜ Network  http://192.168.1.20:4173
watching   content, src
~ content
✓ rebuilt 9 pages · 84ms · reloaded
```

- **`swapSelector` must exist in your layout.** A selector that matches nothing makes every navigation a full page load. An invalid selector throws `[web] spa.swapSelector is not a valid CSS selector` when the browser app is created. On Node there is no DOM to check it, so the build does not catch it.
- **The layout is not re-run.** `.layout()` frames the page at build. On navigation only the swap region changes, so chrome that depends on the page must update itself, for example as a persistent island with `onNavEnd`.
- **One app per page.** The teardown handles live at module scope. Two apps in one page would share them.
- **Programmatic navigation waits for `start()`.** `navigate()` and `app.spa.navigate()` do nothing before the browser app has started, and nothing on Node.

## Related

- [spa plugin](/docs/web/plugins/spa/): config, API, events.
- [Data](/docs/web/guides/data/): the data path in detail.
- [Islands](/docs/web/guides/islands/): persistent and page-specific islands.
- [Routing](/docs/web/guides/routing/): `.transition()` and `.scroll()`.


# Build & deploy

Source: https://moku-labs.com/docs/web/guides/deploy/ · @moku-labs/web@2.4.11

> From app.build.run() to a Cloudflare Pages URL, with one script per command.

## How it fits together

Three Node-only plugins share the job:

- **build** renders every route into `dist/` and writes the site-wide files.
- **deploy** ships `dist/` to Cloudflare Pages through `wrangler`, and scaffolds `wrangler.jsonc`.
- **cli** wraps both in four commands with the branded terminal panel: `build`, `serve`,
  `preview`, `deploy`.

The `cli` plugin has no argument parser and no binary. Each command is a two-line script that
imports your app and calls one method.

- bun run build
- app.cli.build()
- build.run()
- dist/
- app.cli.deploy()
- pages.dev

## Example

```ts
import {
  buildPlugin,
  cliPlugin,
  contentPlugin,
  createApp,
  deployPlugin,
  dotenv,
  fileSystemContent,
  processEnv
} from "@moku-labs/web";
import { routes } from "./routes";

export const app = createApp({
  plugins: [contentPlugin, buildPlugin, deployPlugin, cliPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    content: { providers: [fileSystemContent({ contentDir: "content" })] },
    build: { outDir: "dist", notFound: true, clientEntry: "src/client.tsx" },
    deploy: { outDir: "dist", productionBranch: "main" },
    cli: { outDir: "dist", port: 4173 },
    env: { providers: [processEnv(), dotenv(".env")] }
  }
});
```

1. `cli` depends on `build` and `deploy`, so all three are listed, in this order.
2. The site name becomes the Pages project name: `my-blog`.
3. The deploy reads `CLOUDFLARE_API_TOKEN` through `env`. Without providers it sees nothing.

```ts
import { app } from "../src/app";

await app.cli.build();
```

```ts
import { app } from "../src/app";

await app.cli.serve();
```

```ts
import { app } from "../src/app";

await app.cli.preview();
```

```ts
import { app } from "../src/app";

await app.cli.deploy({ guided: !process.argv.includes("--cli") });
```

1. `bun run deploy` runs the wizard. `bun run deploy --cli` and CI take the direct path.

| Script | Method | What it does |
|---|---|---|
| `bun run build` | `cli.build()` | Runs the build, then checks that `dist/404.html` exists. |
| `bun run dev` | `cli.serve()` | Builds once, serves `dist/` with live reload, watches `content` and `src`, rebuilds on change. |
| `bun run preview` | `cli.preview()` | Serves the built `dist/` with Cloudflare Pages clean URLs and the nearest `404.html`. No reload. |
| `bun run deploy` | `cli.deploy()` | Guided: checks credentials and `wrangler.jsonc`, test-builds, deploys, offers a GitHub workflow. Direct: scaffolds, then deploys. |

## First deploy

1. **Get the credentials.** Create a Cloudflare API token with the "Cloudflare Pages: Edit" permission and note your account ID. Put both in `.env` (keep it out of git) and in the repository secrets for CI.
2. **Run the wizard.** `bun run deploy` checks the prerequisites, offers to scaffold `wrangler.jsonc` and a placeholder `.env`, runs a local build and deploys when everything is green.
3. **Automate.** The wizard offers to write `.github/workflows/deploy.yml`. Or call `app.deploy.init({ ci: true, workflowTrigger: "auto" })` yourself. The triggers are `"auto"` (push to `main`), `"versioned-tag"` (a `v*` tag) and `"dispatch"` (manual).

```sh
$ bun run deploy
▟▙ moku web  deploy                                      v2.4.11
Checking prerequisites
✓ wrangler.jsonc (Cloudflare project config)
✓ CLOUDFLARE_API_TOKEN is set
✓ CLOUDFLARE_ACCOUNT_ID is set
Local test
✓ built 9 pages → dist/
✓ 404.html present
✓ DEPLOYED · main                                             9.4s
→ https://my-blog.pages.dev · 3f2a9c1e
```

## Without the cli plugin

The two plugins also work alone. This script builds and deploys in one go:

```ts
import { buildPlugin, createApp, defineRoutes, deployPlugin, processEnv, route } from "@moku-labs/web";
import { h } from "preact";

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

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

await app.deploy.init();
const built = await app.build.run();
const deployed = await app.deploy.run({ branch: "main" });
console.log(`${built.pageCount} pages → ${deployed.url}`);
```

1. Writes `wrangler.jsonc` once. An existing file is never overwritten.
2. A branch other than the production branch makes a preview deployment.

## What the build writes

| Path | When |
|---|---|
| `<path>/index.html` | every page. In `spa` mode a dynamic route without `generate` is skipped and rendered in the browser |
| `index.html` | when a `/` page was rendered |
| `assets/<name>-<hash>.{css,js}` | always; `minify` is on by default |
| `_data/**/index.json` | `mode` is not `"ssg"` and `data` is composed |
| `feed.xml`, `atom.xml`, `feed.json` | `feeds` (on by default) |
| `sitemap.xml`, `robots.txt` | `sitemap` (on by default) |
| `<slug>/images/…` | `images` (on by default), from co-located article folders |
| `og/<slug>.png`, `og-default.png` | `ogImage` |
| everything in `public/` | `publicDir` exists |
| `_headers` | `cacheHeaders` (on by default) |
| `404.html` | `notFound` |

`build.run()` deletes and recreates `outDir` first. The folder must sit inside the project, or in
the OS temp folder.

- **`deploy` does not build.** It ships whatever is in `outDir`. Build first.
- **`cli.build()` fails without `dist/404.html`.** Set `build.notFound`. Without a top-level `404.html` Cloudflare Pages switches the project to SPA mode.
- **The direct `cli.deploy()` scaffolds a workflow.** It calls `deploy.init({ ci: true })`, which writes `.github/workflows/deploy.yml` when the file is missing, whatever `deploy.ci` says.
- **Wire the env providers.** The deploy reads the token through `ctx.env`, not the raw environment. The wizard says so: "Found in your shell/.env but the app's env plugin did not resolve it".
- **The Pages project must exist.** `deploy.init()` only writes local config. The wizard creates the project after a project-not-found failure, or call `app.deploy.createProject()`.
- **Cloudflare limits.** Preflight stops at 20,000 files and at any file over 25 MiB. Raise the file cap with the `MOKU_DEPLOY_MAX_FILES` environment variable on a paid plan.

## Related

- [build plugin](/docs/web/plugins/build/): every option and the phases.
- [deploy plugin](/docs/web/plugins/deploy/): `run`, `init`, the error codes.
- [cli plugin](/docs/web/plugins/cli/): the five methods and the panel.
- [Head & SEO](/docs/web/guides/head/): feeds, sitemap and OG images.


# build

Source: https://moku-labs.com/docs/web/plugins/build/ · @moku-labs/web@2.4.11

> Node-only. The static build: every route to HTML, plus bundles, feeds, sitemap, OG images and cache headers.

## 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](/docs/web/plugins/cli/).

## 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:

| Phase | What it does | Runs when |
|---|---|---|
| clean | Deletes and recreates `outDir`. | always, unless `run({ skipClean: true })` |
| `bundle` | `Bun.build` for CSS and JS, separately, with a content hash in every file name. | always |
| `content` | `content.loadAll()`, cached for the later phases. | always; empty without `content` |
| `images` | Copies static image folders. | `images` |
| `pages` | `generate` → `load` → `head.render` → `render` for every page, then the JSON sidecars. | always |
| `content-images` | Copies each article's co-located folders to `<slug>/…`. | `images` |
| `feeds` | `feed.xml`, `atom.xml`, `feed.json`. | `feeds` |
| `sitemap` | `sitemap.xml`, `robots.txt`. | `sitemap` |
| `og-images` | One PNG per article with Satori, plus `og-default.png`. | `ogImage` |
| `public` | Copies `publicDir` as it is. | the folder exists |
| `not-found` | `404.html`. | `notFound` |
| `locale-redirects` | Redirect pages for bare locale paths. | `localeRedirects` |
| `cache-headers` | `_headers` with cache rules, then your `public/_headers`. | `cacheHeaders` |
| `root-index` | Writes the `/` page to `index.html`. | a `/` page was rendered |

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.

| Option | Type | Default | Description |
|---|---|---|---|
| `outDir` | `string` | `"./dist"` | Output folder. Must be inside the project or the OS temp folder: it is deleted on every run. |
| `minify` | `boolean` | `true` | Minify the CSS and JS bundles. |
| `feeds` | `boolean` | `true` | RSS, Atom and JSON feeds from the content articles. |
| `sitemap` | `boolean` | `true` | `sitemap.xml` and `robots.txt`. |
| `images` | `boolean` | `true` | Copy static images and co-located article folders. |
| `ogImage` | `OgImageConfig \| false` | `false` | OG image generation. An object turns it on. |
| `injectAssets` | `boolean` | `true` | Add the bundle `<link>` and `<script>` tags to every page. |
| `publicDir` | `string` | `"public"` | Copied into `outDir` as it is. Skipped when missing. |
| `notFound` | `boolean \| { body?, path? }` | `false` | `true`: a built-in page. `{ body }`: your HTML in a minimal shell. `{ path }`: your complete HTML file. |
| `localeRedirects` | `boolean` | `false` | Redirect pages for bare locale paths. |
| `clientEntry` | `string` | the scan above | The client bundle entry. |
| `env` | `readonly string[]` | none | Variable names written into the client bundle as constants. |
| `template` | `string` | built-in shell | Path to your HTML shell with `<!--moku:lang-->`, `<!--moku:head-->`, `<!--moku:assets-->`, `<!--moku:assets:css-->`, `<!--moku:assets:js-->` and `<!--moku:body-->`. |
| `cacheHeaders` | `boolean \| { assets?, pages? }` | `true` | `_headers` rules. Hashed bundles: `public, max-age=31536000, immutable`. Everything else: `public, max-age=0, must-revalidate`. |

`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)`.

| Method | Signature | Description |
|---|---|---|
| `run` | `(options?: RunOptions) => Promise<BuildResult>` | Runs the build. Resolves to `{ outDir, pageCount, durationMs }`. |
| `phases` | `() => PhaseName[]` | The phase names in order. |

`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

| Event | Payload | When |
|---|---|---|
| `build:phase` | `{ phase: PhaseName; status: "start" \| "done"; durationMs?: number }` | At each phase boundary. `durationMs` only on `"done"`. |
| `build:complete` | `{ outDir: string; pageCount: number; durationMs: number }` | Once, after a successful run. |

### Listens to

None.

## Depends on

- [site](/docs/web/plugins/site/), [router](/docs/web/plugins/router/) and
  [head](/docs/web/plugins/head/): required, in `depends`.
- [content](/docs/web/plugins/content/) and [i18n](/docs/web/plugins/i18n/): optional. A site
  without content builds zero articles; without i18n it builds the `"en"` locale.
- [data](/docs/web/plugins/data/): optional. When composed and the mode is not `"ssg"`, the pages
  phase writes the JSON sidecars.

## Example

```ts
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}`);
```

1. Makes the build events visible to `hooks`, with typed payloads.
2. No content plugin here, so there is nothing to put in a feed.

```sh
$ 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.

- **`build:complete` handlers are not awaited.** Hooks are notifications. Work that must finish before the process exits goes after `await app.build.run()`.
- **`outDir` is deleted on every run.** `"./"`, your home folder or the project root fail with `[web] build.outDir: … is not a safe clean target.`
- **`ogImage.fontDir` is checked at `createApp`.** A missing folder or a folder without a font fails before the build starts.
- **No client entry is a warning, not an error.** Without `clientEntry` and without one of the scanned files, the build logs `build:bundle` with `clientEntry: "none"` and ships no JS.
- **Hard-coded bundle URLs break.** Bundle names carry a hash. In a `notFound` page or a `template`, use the `<!--moku:assets-->` placeholders.
- **`build` writes; it does not serve or deploy.** Use [cli](/docs/web/plugins/cli/) for a dev server and [deploy](/docs/web/plugins/deploy/) to ship.

## Related

- [Build & deploy](/docs/web/guides/deploy/): the scripts and the first deploy.
- [Head & SEO](/docs/web/guides/head/): feeds, sitemap and OG images.
- [Data](/docs/web/guides/data/): the JSON sidecars.


# cli

Source: https://moku-labs.com/docs/web/plugins/cli/ · @moku-labs/web@2.4.11

> Node-only. build, serve, preview and deploy as app methods, with the branded terminal panel.

## What it does

**Node-only.** `cli` turns the build and the deploy into five methods at `app.cli`. Four of them
back one script each: `build`, `serve`, `preview`, `deploy`. The fifth, `update`, is a headless
incremental rebuild for an external dev loop, such as a `@moku-labs/worker` dev session that
serves this site.

There is no argument parser, no `run()` dispatcher and no binary. A script names its command by
calling it.

## How it works

`cli` depends on `build` and `deploy` and calls them at run time. It renders live progress by
hooking their events: every `build:phase` becomes a row, `build:complete` becomes the BUILD box,
`deploy:complete` the DEPLOYED box.

On a terminal the panel is animated: the `▟▙ moku web` lockup with the version and runtime, a
live phase tree, boxed results and a breathing "live" line while the dev server waits. In CI and
pipes, or with `NO_COLOR`, it prints plain lines: one per finished phase, no animation.

The dev server, the preview server and the file watcher live inside `serve()` and `preview()`
and close on Ctrl+C. The plugin itself holds no resource, so it has no `onStart` or `onStop`.

## Config

`pluginConfigs.cli`. Every field has a default.

| Option | Type | Default | Description |
|---|---|---|---|
| `outDir` | `string` | `"dist"` | The build output: served by `preview`, checked by `build`, rebuilt by `serve`. |
| `port` | `number` | `4173` | Port for `serve()` and `preview()`. Overridable per call. |
| `watchDirs` | `string[]` | `["content", "src"]` | Folders `serve()` watches, recursively. |
| `debounceMs` | `number` | `150` | Window that merges a burst of file events into one rebuild. |
| `notFoundFile` | `string` | `"404.html"` | The file `build()` requires at the root of `outDir`. |
| `liveReload` | `boolean` | `true` | Inject the live-reload client into pages during `serve()`. Never during `preview()`. |

`createApp` fails with code `ERR_CLI_CONFIG` when `port` is not an integer from 1 to 65535,
`outDir` or `notFoundFile` is empty, `watchDirs` is empty or `debounceMs` is negative.

## API

Mounted at `app.cli`, reachable with `ctx.require(cliPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `build` | `(options?: { assertNotFound?: boolean }) => Promise<BuildSummary>` | Runs `build.run()`, then checks `<outDir>/<notFoundFile>`. Throws `ERR_CLI_NOT_FOUND` when it is missing. |
| `update` | `(changes: readonly string[], options?: { og?, sitemap?, feeds? }) => Promise<BuildSummary>` | Incremental rebuild for the changed paths. No header, no 404 check. OG images, sitemap and feeds stay off unless turned on. |
| `serve` | `(options?: { port?, open?, og?, sitemap?, feeds? }) => Promise<void>` | Builds once, serves `outDir` with live reload, watches `watchDirs`, rebuilds and reloads. Resolves on Ctrl+C. `open` is reserved. |
| `preview` | `(options?: { port? }) => Promise<void>` | Serves the built `outDir` like Cloudflare Pages: `/a/` → `a/index.html`, a miss → the nearest `404.html` with status 404. |
| `deploy` | `(options?: { branch?, yes?, guided? }) => Promise<DeployOutcome>` | `guided: true` runs the setup wizard. Otherwise: `deploy.init({ ci: true })`, a y/N prompt on an interactive terminal only, then `deploy.run()`. |

`BuildSummary` is `{ outDir, pageCount, durationMs }`. `DeployOutcome` is
`{ deployed: true, url, deploymentId, branch, durationMs }` or
`{ deployed: false, reason: "declined" | "blocked" | "failed" }`.

## Events

### Emits

None.

### Listens to

| Event | Source | What it renders |
|---|---|---|
| `build:phase` | build | A phase row: spinner while running, `✓` and the time when done. |
| `build:complete` | build | The BUILD box with the page count, time and output folder. |
| `deploy:complete` | deploy | The DEPLOYED box with the branch, time and URL. |

## Depends on

- [build](/docs/web/plugins/build/): `run()` for `build`, `update` and `serve`.
- [deploy](/docs/web/plugins/deploy/): `init()` and `run()` for `deploy`.

Both are Node-only, so `cli` is too. List them before it: `plugins: [buildPlugin, deployPlugin, cliPlugin]`.

## Example

```ts
import { buildPlugin, cliPlugin, createApp, defineRoutes, deployPlugin, processEnv, route } from "@moku-labs/web";
import { h } from "preact";

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

export const app = createApp({
  plugins: [buildPlugin, deployPlugin, cliPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    router: { routes },
    build: { outDir: "dist", notFound: true },
    cli: { outDir: "dist", port: 3000, watchDirs: ["content", "src", "public"] },
    env: { providers: [processEnv()] }
  }
});

const summary = await app.cli.build();
console.log(summary.pageCount);
```

1. Watch `public/` too, so a changed image triggers a rebuild.
2. In a real project this line is the whole of `scripts/build.ts`.

```sh
$ bun run build
▟▙ moku web  build                                       v2.4.11
✓ bundle · 5ms
✓ content · 1239ms
✓ pages · 5ms
✓ not-found · 1ms
✓ sitemap · 1ms
✓ cache-headers · 0ms
✓ root-index · 0ms
✓ BUILD · 9 pages                                1252ms · ./dist/
```

- **`build()` needs the 404 page.** Set `build.notFound`, or pass `{ assertNotFound: false }`. Cloudflare Pages switches a project without a top-level `404.html` to SPA mode.
- **The direct `deploy()` writes a workflow.** It calls `deploy.init({ ci: true })`, so `.github/workflows/deploy.yml` appears when it is missing.
- **The prompt never blocks CI.** The y/N confirm shows only on an interactive terminal with `CI` unset. `{ yes: true }` skips it anywhere.
- **A failed direct deploy is re-thrown.** The panel prints the cause and a hint, then the error propagates, so CI exits non-zero.
- **`serve()` skips expensive outputs.** OG images, sitemap and feeds are off in the dev loop unless you pass `og`, `sitemap` or `feeds`.

## Related

- [Build & deploy](/docs/web/guides/deploy/): the scripts and the first deploy.
- [build plugin](/docs/web/plugins/build/) and [deploy plugin](/docs/web/plugins/deploy/).


# collection

Source: https://moku-labs.com/docs/web/plugins/collection/ · @moku-labs/web@2.4.11

> Optional provider. (collection, shard) → JSON file: written at build, fetched on demand in the browser.

## What it does

**Optional provider.** `collection` owns one contract: a `(collection, shard)` key maps to one
JSON file. On Node, `write(entries)` persists the shards your build script authored. In the
browser, `at(collection, shard)` fetches and caches one of them.

It knows nothing about what the data is. A search index, a question bank, a dictionary: you pick
the shape. It is the collection-keyed sibling of the page-keyed [data](/docs/web/plugins/data/)
plugin.

## How it works

`urlFor` and `fileFor` both come from one function, so the file `write` creates is exactly the
URL `at` fetches. The shard key may contain `/`, which becomes nested folders. Outer slashes are
trimmed.

| `(collection, shard)` | `fileFor` | `urlFor` with `baseUrl: "/"` |
|---|---|---|
| `("bank", "ru")` | `bank/ru.json` | `/bank/ru.json` |
| `("bank", "en/animals")` | `bank/en/animals.json` | `/bank/en/animals.json` |
| `("/bank/", "/en/")` | `bank/en.json` | `/bank/en.json` |

`write` serializes each shard's `data` with `JSON.stringify`, at most 8 files at a time. Its
`node:fs` writer is loaded lazily, so composing the plugin in a browser bundle pulls no `node:*`
module. `at` returns `null` when the fetch or the parse fails, so the caller can fall back.

## Config

`pluginConfigs.collection`.

| Option | Type | Default | Description |
|---|---|---|---|
| `baseUrl` | `string` | `"/"` | The URL prefix the browser fetches shards from. Must end with `/`. |

## API

Mounted at `app.collection`, reachable with `ctx.require(collectionPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `write` | `(entries: readonly CollectionShard[], options?: { outDir?: string }) => Promise<CollectionWriteSummary>` | Node. One file per entry. `outDir` defaults to `./dist`. Resolves to `{ fileCount, bytes, files }`. |
| `at` | `(collection: string, shard: string) => Promise<unknown \| null>` | Browser. Fetches and caches one shard. `null` on failure. |
| `urlFor` | `(collection: string, shard: string) => string` | The fetch URL. |
| `fileFor` | `(collection: string, shard: string) => string` | The `outDir`-relative file path. |

`CollectionShard` is `{ collection: string; shard: string; data: unknown }`.

## Events

### Emits

None.

### Listens to

None.

## Depends on

Nothing. The relationship to the build is a call you make: write the shards after
`app.build.run()`, which deletes `outDir` first.

## Example

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

const words = { en: ["cat", "dog"], uk: ["кіт", "пес"] };

const routes = defineRoutes({ home: route("/").render(() => h("h1", null, "Words")) });

const app = createApp({
  plugins: [collectionPlugin, buildPlugin],
  pluginConfigs: {
    site: { name: "Words", url: "https://words.dev", author: "Ada", description: "A word game." },
    router: { routes },
    build: { outDir: "dist", feeds: false }
  }
});

await app.build.run();
const summary = await app.collection.write(
  Object.entries(words).map(([locale, list]) => ({ collection: "bank", shard: `${locale}/animals`, data: list })),
  { outDir: "dist" }
);
console.log(summary.files); // ["bank/en/animals.json", "bank/uk/animals.json"]
```

1. After the build: `build.run()` empties `outDir` first.

```ts
import { collectionUrl, loadCollectionShard } from "@moku-labs/web/browser";

export async function loadWords(locale: string): Promise<string[]> {
  return loadCollectionShard<string[]>("/", "bank", `${locale}/animals`);
}

export const englishUrl = collectionUrl("/", "bank", "en/animals"); // "/bank/en/animals.json"
```

1. Throws on a non-OK response. Wrap it when a miss is expected.

- **`collectionPlugin` is not exported from `@moku-labs/web/browser` in 2.4.11.** In the client bundle use `loadCollectionShard` and `collectionUrl`, which are.
- **`at` returns `unknown`.** There is no validation step. Check the shape before you trust it.
- **`loadCollectionShard` throws; `at` returns `null`.** Pick the one whose failure mode fits the caller.
- **`baseUrl` must end with `/`.** Otherwise `createApp` throws `[web] collection.baseUrl: must be a URL prefix ending with "/" (e.g. "/" or "/cdn/").`

## Related

- [Content & collections](/docs/web/guides/content/): a search index built from the articles.
- [data plugin](/docs/web/plugins/data/): the same idea keyed by page path.


# content

Source: https://moku-labs.com/docs/web/plugins/content/ · @moku-labs/web@2.4.11

> Node build. Markdown articles to sanitized HTML, with frontmatter, reading time, locale fallback and drafts.

## What it does

**Node build.** `content` gives you a locale-keyed model of Markdown articles. Each
`content/<slug>/<locale>.md` becomes an `Article` with its frontmatter, computed fields and
rendered HTML. Routes read it in build-only loaders with `ctx.require(contentPlugin)`.

The plugin itself imports no Node code and is exported from both entries, so a route file can
`ctx.require(contentPlugin)` in either app. The reading and rendering happen in a **provider**.
`fileSystemContent`, the Node provider, is exported from `@moku-labs/web` only.

## How it works

The plugin is a shell around providers, the same way `env` works with env providers:

| The shell owns | The provider owns |
|---|---|
| Locale fallback | Finding slugs |
| Draft filtering by stage | Reading `<slug>/<locale>.md` |
| Date sort, newest first | Frontmatter parsing |
| `contentId` assignment | The Markdown pipeline and Shiki |
| The article cache | The rendered HTML |
| `content:ready` and `content:invalidated` | |

With several providers, `slugs()` are merged and the first provider that has a slug and locale
wins.

The `fileSystemContent` pipeline: frontmatter, then remark (GitHub-flavoured Markdown, the
directive syntax, your `extraRemarkPlugins`), then rehype (raw HTML, the framework transforms,
your `extraRehypePlugins`), then Shiki, then `rehype-sanitize` when `trustedContent` is `false`.
The processor is built on the first render and kept inside the provider.

Computed fields:

| Field | Value |
|---|---|
| `slug` | The folder name. |
| `readingTime` | Minutes, rounded up, at least 1. |
| `wordCount` | Words in the source body. |
| `status` | `"draft"` when the frontmatter has `draft: true`, else `"published"`. |
| `contentId` | The slug on a single `load`. After `loadAll` sorts: `<locale>:<index>:<slug>`, e.g. `uk:0000:second-post`. |

Frontmatter dates become ISO `YYYY-MM-DD` strings. Relative image paths such as
`./images/cover.png` become `/<slug>/images/cover.png`, so they work from every locale page.

## Config

`pluginConfigs.content`.

| Option | Type | Default | Description |
|---|---|---|---|
| `providers` | `ContentProvider[]` | `[]` | Content sources, in order. At least one is required: the empty default fails `createApp`. |

`fileSystemContent(options)`:

| Option | Type | Default | Description |
|---|---|---|---|
| `contentDir` | `string` | required | The article root, absolute or relative to the project. |
| `trustedContent` | `boolean` | `false` | `false` sanitizes the HTML last. `true` skips sanitize. Use it only for Markdown you write yourself. |
| `shikiTheme` | `BundledTheme \| ThemeRegistrationAny` | `"github-dark"` | Passed to `@shikijs/rehype`. |
| `defaultAuthor` | `string` | none | Author for articles without one. |
| `extraRemarkPlugins` | `readonly Pluggable[]` | `[]` | Added after the framework remark plugins. |
| `extraRehypePlugins` | `readonly Pluggable[]` | `[]` | Added after the framework transforms, before Shiki and sanitize. |
| `mermaid` | `boolean \| MermaidDiagramOptions` | off | `mermaid` fences to inline SVG at build. Needs `trustedContent` and `mermaid-isomorphic`. A diagram that fails fails the build. |
| `embed` | `boolean \| { facade? }` | off | `::embed{src title width? height?}` to a click-to-load facade. Needs `trustedContent` and the `lazyEmbed` island. |
| `gallery` | `boolean \| { component? }` | off | `::gallery{src caption?}` to an image set from a co-located folder. Needs `trustedContent`. |

The `extra*` options add to the framework plugins and never replace them. A full plugin array in
config would be replaced by the shallow config merge, which is why there is none.

## API

Mounted at `app.content`, reachable with `ctx.require(contentPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `loadAll` | `(options?: { reuse?: boolean }) => Promise<Map<string, Article[]>>` | Every article of every locale, newest first, with fallback. Cached: repeated calls return the same object. `{ reuse: false }` reloads everything. Emits `content:ready`. |
| `load` | `(slug: string, locale: string) => Promise<Article>` | One article with fallback. Throws `[web] content article "…" not found for locale "…".` |
| `renderMarkdown` | `(md: string) => Promise<string>` | Renders a Markdown string through the provider pipeline. |
| `invalidate` | `(paths: readonly string[]) => void` | Marks files stale for the next dev rebuild. Emits `content:invalidated`. |
| `articleToCard` | `(article: Article) => ArticleCard` | A light projection without HTML, for lists. |
| `contentDir` | `() => string` | The first provider's folder. The build copies co-located assets from it. |

`ArticleCard` is `{ contentId, status, title, date, description, tags, readingTime, url }`.

## Events

### Emits

| Event | Payload | When |
|---|---|---|
| `content:ready` | `{ locales: readonly string[]; articleCount: number }` | At the end of every `loadAll()` that loaded. |
| `content:invalidated` | `{ paths: readonly string[] }` | On `invalidate(paths)`, with the accepted, non-empty paths. |

### Listens to

None.

## Depends on

Nothing in `depends`. [i18n](/docs/web/plugins/i18n/) is read when present: its locales decide
what `loadAll` iterates and its default locale is the fallback. Without it there is one locale,
`"en"`.

## Example

```ts
import { contentPlugin, createApp, createPlugin, fileSystemContent } from "@moku-labs/web";

const statsPlugin = createPlugin("stats", {
  depends: [contentPlugin],
  hooks: ctx => ({
    "content:ready": ({ locales, articleCount }) => ctx.log.info("content:stats", { locales, articleCount })
  })
});

const app = createApp({
  plugins: [contentPlugin, statsPlugin],
  config: { stage: "development" },
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
    content: {
      providers: [fileSystemContent({ contentDir: "content", shikiTheme: "github-light", defaultAuthor: "Ada" })]
    }
  }
});

const byLocale = await app.content.loadAll();
console.log([...byLocale].map(([locale, articles]) => `${locale}: ${articles.length}`));

const article = await app.content.load("second-post", "uk");
console.log(article.isFallback, article.url); // true "/uk/second-post/"

const html = await app.content.renderMarkdown("Inline `code` and **bold**.");
console.log(html); // "<p>Inline <code>code</code> and <strong>bold</strong>.</p>"
```

1. Drafts load in `development` and `test`. In `production`, the default, they are left out.
2. Emits `content:ready`, which the stats plugin logs.

```sh
$ bun scripts/stats.ts
{ level: "info", event: "content:stats", data: { locales: [ "en", "uk" ], articleCount: 4 } }
[ "en: 2", "uk: 2" ]
true /uk/second-post/
<p>Inline <code>code</code> and <strong>bold</strong>.</p>
```

Two articles in two locales count as four: `second-post` has no `uk.md`, and its fallback copy
in the `uk` list counts too.

- **No provider, no app.** `providers: []` fails `createApp` with `[web] content: no provider composed.`
- **`mermaid`, `embed` and `gallery` need `trustedContent: true`.** `fileSystemContent` throws at construction otherwise: their output is raw HTML the sanitizer would strip.
- **Five frontmatter fields are required.** `title`, `date`, `description`, `tags`, `language`. A missing one throws `[web] content frontmatter is missing required field "…".`
- **Drafts depend on the global stage.** `stage: "production"`, the default, hides them everywhere, and `load()` of a draft throws the not-found error.
- **The `loadAll()` result is shared.** It is the cached object. Copy before you sort or filter in place.
- **`fileSystemContent` is not in `@moku-labs/web/browser`.** The browser entry has the shell only, for typing and `ctx.require`.

## Related

- [Content & collections](/docs/web/guides/content/): the guide with a full blog.
- [Routing](/docs/web/guides/routing/): `generate` and `load` with `ctx.require(contentPlugin)`.
- [build plugin](/docs/web/plugins/build/): the `content` and `content-images` phases.


# data

Source: https://moku-labs.com/docs/web/plugins/data/ · @moku-labs/web@2.4.11

> Optional provider. Page path → JSON file: the build writes each page's load() result, spa fetches it on navigation.

## What it does

**Optional provider.** `data` is the transport of the SSG → DATA → SPA pattern. It owns one
contract: a page path maps to one JSON file. On Node, the build calls `write(entries)` with the
`load` result of every rendered page. In the browser, `spa` calls `at(path)` on navigation and
passes the JSON to the route's `render` as `ctx.data`.

It is exported from both entries. Compose it on both sides for data navigation.

## How it works

`data` declares no dependencies. The link to the other plugins is a call they make:

- `build` checks `ctx.has("data")` in its pages phase. When `data` is there and
  `router.mode()` is not `"ssg"`, it writes one sidecar per page that has a `render`.
- `spa` checks `ctx.has("data")` while the browser app is created. When `data` is there and the
  mode is not `"ssg"`, navigation tries the data path before HTML-over-fetch.

`urlFor` and `fileFor` come from one function, so the written file is the fetched URL:

| Page path | `fileFor` | `urlFor` |
|---|---|---|
| `/` | `_data/index.json` | `/_data/index.json` |
| `/en/hello/` | `_data/en/hello/index.json` | `/_data/en/hello/index.json` |
| `/en/hello` | `_data/en/hello/index.json` | `/_data/en/hello/index.json` |

`write` stores each entry's `data` with `JSON.stringify`, at most 8 files at a time, through a
lazily loaded `node:fs` writer. The browser bundle gets no Node code from it.

## Config

`pluginConfigs.data`.

| Option | Type | Default | Description |
|---|---|---|---|
| `outputDir` | `string` | `"_data"` | Write side: the folder under the build `outDir`. |
| `baseUrl` | `string` | `"/_data/"` | Read side: the URL the browser fetches from. Must start with `/`. Keep it equal to `"/" + outputDir + "/"`. |

## API

Mounted at `app.data`, reachable with `ctx.require(dataPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `write` | `(entries: readonly DataEntry[], options?: { outDir?: string }) => Promise<DataWriteSummary>` | Node. One file per entry. `outDir` defaults to `./dist`. Resolves to `{ fileCount, bytes, files }`. |
| `at` | `(path: string) => Promise<unknown \| null>` | Browser. Fetches and caches a page's JSON. `null` when the fetch or the parse fails. |
| `urlFor` | `(path: string) => string` | The fetch URL of a page. |
| `fileFor` | `(path: string) => string` | The `outDir`-relative file of a page. |

`DataEntry` is `{ path: string; data: unknown }`.

## Events

### Emits

None.

### Listens to

None.

## Depends on

Nothing. `build` and `spa` find it by name when it is composed.

## Example

```ts
import { createApp, dataPlugin } from "@moku-labs/web";

const app = createApp({
  plugins: [dataPlugin],
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    data: { outputDir: "_page", baseUrl: "/_page/" }
  }
});

const summary = await app.data.write(
  [
    { path: "/", data: { title: "Home" } },
    { path: "/about/", data: { title: "About" } }
  ],
  { outDir: "dist" }
);

console.log(summary.files); // ["_page/index.json", "_page/about/index.json"]
console.log(app.data.urlFor("/about/")); // "/_page/about/index.json"
```

1. Change both together: one is a folder, the other its URL.

You rarely call `write` yourself: the build does it for every page. Call it for pages the build
does not render, for example a JSON payload made by another script.

- **Both sides or neither.** Node only: the files are written but never read. Browser only: every fetch misses and navigation falls back to HTML.
- **`ssg` mode turns it off.** The build writes no sidecars and `spa` skips the data path.
- **`at` returns the JSON as it is.** No validation. The route's `render` gets it directly as `ctx.data`.
- **`baseUrl` must start with `/`.** Otherwise `createApp` throws `[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`

## Related

- [Data](/docs/web/guides/data/): the guide.
- [How it works](/docs/web/how-it-works/): the build-to-SPA picture.
- [collection plugin](/docs/web/plugins/collection/): the same idea keyed by collection and shard.


# deploy

Source: https://moku-labs.com/docs/web/plugins/deploy/ · @moku-labs/web@2.4.11

> Node-only. Ships the built site to Cloudflare Pages through wrangler, and scaffolds wrangler.jsonc and a CI workflow.

## What it does

**Node-only.** `deploy` ships `outDir` to Cloudflare Pages by running `wrangler pages deploy` in
a subprocess. It also writes the local scaffolding: `wrangler.jsonc`, and on request a GitHub
Actions workflow. Nothing happens until you call it: `app.deploy.run()` or `app.deploy.init()`.

## How it works

The Pages project name is not config. It is `site.name()` as a slug: `My Cool Blog!` deploys to
`my-cool-blog`. `run()` and `init()` both use it, so the project and the scaffold cannot drift.

Every `run()` goes through the same checks, cheap first, and stops at the first failure:

1. **Preflight.** `wrangler.jsonc` exists, `outDir` exists and is not empty, at most 20,000 files, no file over 25 MiB.
2. **Guards.** `outDir` resolves inside the project. The branch matches `/^[a-zA-Z0-9/_.-]+$/`, so it cannot be read as a flag.
3. **Token.** `CLOUDFLARE_API_TOKEN` is read with `ctx.env.require` and passed to the subprocess environment only: never in the arguments, never logged.
4. **Deploy.** `bunx wrangler pages deploy <outDir> --project-name <slug> --branch <branch>`, spawned with an argument list, no shell.
5. **Report.** All subprocess output is scrubbed before it is logged: long, high-entropy tokens become `***`. On success the result is stored and `deploy:complete` is emitted.

A failure throws an `Error` with a `code`: `ERR_DEPLOY_NO_WRANGLER_CONFIG`,
`ERR_DEPLOY_EMPTY_OUTDIR`, `ERR_DEPLOY_TOO_MANY_FILES`, `ERR_DEPLOY_FILE_TOO_LARGE`,
`ERR_DEPLOY_PATH_TRAVERSAL`, `ERR_DEPLOY_INVALID_BRANCH`, `ERR_DEPLOY_NO_TOKEN`,
`ERR_DEPLOY_PROJECT_NOT_FOUND`, `ERR_DEPLOY_AUTH_EXPIRED`, `ERR_DEPLOY_AUTH`,
`ERR_DEPLOY_NETWORK`, `ERR_DEPLOY_WRANGLER_FAILED` or `ERR_DEPLOY_CONFIG`.

## Config

`pluginConfigs.deploy`. Every field has a default.

| Option | Type | Default | Description |
|---|---|---|---|
| `target` | `"cloudflare-pages"` | `"cloudflare-pages"` | The only target in 2.4.11. |
| `outDir` | `string` | `"dist"` | The built site, relative to the project root. Checked again on every `run()`. |
| `productionBranch` | `string` | `"main"` | The branch `run()` deploys when you pass none. |
| `scrubAllowlist` | `string[]` | `["CLOUDFLARE_ACCOUNT_ID"]` | Substrings that are never masked in logged output. |
| `compatibilityDate` | `string` | `"2024-01-01"` | Written into the generated `wrangler.jsonc`. `YYYY-MM-DD`. |
| `ci` | `boolean` | `false` | Whether `init()` also writes `.github/workflows/deploy.yml`. |

`createApp` fails with `ERR_DEPLOY_CONFIG` on an unknown target, an empty `outDir`, a
`scrubAllowlist` that is not a list of strings or a malformed `compatibilityDate`. The file cap
can be raised toward the paid-plan limit with the `MOKU_DEPLOY_MAX_FILES` environment variable.

## API

Mounted at `app.deploy`, reachable with `ctx.require(deployPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `run` | `(options?: { branch?: string }) => Promise<DeployResult>` | Deploys `outDir`. Resolves to `{ url, deploymentId, branch, durationMs }`. |
| `init` | `(options?: { ci?, check?, workflowTrigger? }) => Promise<InitResult>` | Writes `wrangler.jsonc` (never overwrites it) and, with `ci`, the workflow. `check: true` writes nothing and reports drift. Resolves to `{ written, skipped, drifted }`. |
| `getLastDeployment` | `() => Readonly<DeployResult> \| null` | The last successful deploy of this process, or `null`. |
| `projectName` | `() => string` | The Pages project slug, from `site.name()`. |
| `createProject` | `() => Promise<{ name, branch }>` | Runs `wrangler pages project create` for the slug and the production branch. Fails when the project exists. |

`workflowTrigger` is `"auto"` (push to `main`, the default), `"versioned-tag"` (a `v*` tag) or
`"dispatch"` (the manual button only). The generated workflow pins every action to a commit SHA
and reads the secrets `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`.

## Events

### Emits

| Event | Payload | When |
|---|---|---|
| `deploy:complete` | `{ url: string; deploymentId: string; branch: string; durationMs: number }` | Once, after a successful deploy. A failed one emits nothing. |

### Listens to

None.

## Depends on

- [site](/docs/web/plugins/site/): `name()`, for the project slug.
- The core `env` plugin: `ctx.env.require("CLOUDFLARE_API_TOKEN")`. Wire Node env providers in
  `pluginConfigs.env`, for example `[processEnv(), dotenv(".env")]`.

## Example

```ts
import { createApp, deployPlugin, dotenv, processEnv } from "@moku-labs/web";

const app = createApp({
  plugins: [deployPlugin],
  pluginConfigs: {
    site: { name: "My Cool Blog!", url: "https://blog.dev", author: "Ada", description: "Notes." },
    deploy: { outDir: "dist", productionBranch: "main" },
    env: { providers: [processEnv(), dotenv(".env")] }
  }
});

console.log(app.deploy.projectName()); // "my-cool-blog"

const scaffold = await app.deploy.init({ ci: true, workflowTrigger: "versioned-tag" });
console.log(scaffold.written); // ["wrangler.jsonc", ".github/workflows/deploy.yml"] on the first run

const result = await app.deploy.run({ branch: "preview/landing" });
console.log(result.url);
```

1. Run it once. Later runs skip files that exist.
2. Ships whatever is in `dist/`. Build first.

```sh
$ bun scripts/deploy.ts
my-cool-blog
[ "wrangler.jsonc", ".github/workflows/deploy.yml" ]
https://….pages.dev
```

The URL is the one wrangler printed for the deployment.

- **`deploy` does not build.** Run `app.build.run()` or `app.cli.build()` first.
- **`init()` does not create the Pages project.** It only writes local files. The first deploy to a new project fails with `ERR_DEPLOY_PROJECT_NOT_FOUND`: create it in the dashboard, with `createProject()`, or let the `cli` wizard do it.
- **The token comes through `env`.** A token in your shell is invisible to the plugin until an env provider such as `processEnv()` is composed.
- **Renaming the site renames the project.** The slug follows `site.name`. Rename both on purpose.
- **Runs under Bun.** The default spawner is `Bun.spawn`. Without Bun, `run()` throws `ERR_DEPLOY_WRANGLER_FAILED`.

## Related

- [Build & deploy](/docs/web/guides/deploy/): the scripts, the wizard and CI.
- [cli plugin](/docs/web/plugins/cli/): `app.cli.deploy()` with the guided wizard.


# head

Source: https://moku-labs.com/docs/web/plugins/head/ · @moku-labs/web@2.4.11

> Default. Composes the <head> of every page: title template, description, Open Graph, Twitter, canonical, hreflang, extras.

## What it does

**Isomorphic default.** `head` owns everything inside `<head>`. The build calls it for every
page; `spa` uses it to set the title on client navigation. It emits no events and listens to
none. Its only state is the normalized defaults, frozen while `createApp` runs.

It also carries the head helpers, `meta`, `og`, `twitter`, `jsonLd`, `canonical`, `hreflang`,
`feedLink` and `buildArticleHead`, exported from both entries for use in `.head()`.

## How it works

`render(route, data)` composes a list of head elements, then serializes it:

1. **Title.** `titleTemplate` applied to the route title, or to `site.name()`.
2. **Description.** The route description, or `site.description()`.
3. **Open Graph and Twitter.** `og:title`, `og:description`, `og:url`, the image from the route or `defaultOgImage` made absolute, `twitter:card`, `twitter:site` when `twitterHandle` is set, `og:locale` when `i18n.ogLocale(locale)` has a value.
4. **Canonical.** The route `canonical`, or `site.canonical(router.toUrl(name, params))`.
5. **hreflang.** One alternate per `i18n.locales()`, plus `x-default`.
6. **Route elements.** The `elements` from `.head()`, last.

Then elements with the same `key` are de-duplicated, last one wins. Generated tags carry keys
such as `meta:description`, `link:canonical` and `link:alternate:uk`, so a route element with
the same key replaces the default. Elements without a key, such as JSON-LD, are always kept.
Attribute values and the title are HTML-escaped when serialized; `jsonLd` escapes `<`, `>` and
`&` when it is built.

A head element is a plain `{ tag, attrs?, children?, key? }` object, not a Preact node, so the
plugin needs no renderer.

## Config

`pluginConfigs.head`. Every field is optional.

| Option | Type | Default | Description |
|---|---|---|---|
| `titleTemplate` | `string` | none | `%s` is replaced by the route title. Without `%s`, `createApp` throws. |
| `defaultOgImage` | `string` | none | `og:image` and `twitter:image` for pages without their own. Relative paths resolve against `site.url`. |
| `twitterCard` | `"summary" \| "summary_large_image"` | `"summary_large_image"` | The `twitter:card` value. Anything else throws. |
| `twitterHandle` | `string` | none | `twitter:site`, e.g. `"@moku_labs"`. |

## API

Mounted at `app.head`, reachable with `ctx.require(headPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `render` | `(route: ResolvedRoute, data: unknown) => string` | The inner HTML of `<head>` for a page, without the `<head>` tags. The build calls it for every page. |
| `siteHead` | `(input: { url: string; locale?: string }) => string` | A site-level Open Graph block for a page with no route, such as a bare redirect. `""` unless `defaultOgImage` is set. |
| `composeTitle` | `(head: HeadConfig \| undefined) => string` | The final title for a route's head config, the same text `render` puts in `<title>`. |

`ResolvedRoute` is `{ path, name, params, locale?, head? }`, where `head` is the route's
`HeadConfig`: `{ title?, description?, canonical?, image?, elements? }`.

### Helpers

| Helper | Signature | Key |
|---|---|---|
| `meta` | `(name: string, content: string) => HeadElement` | `meta:<name>` |
| `og` | `(property: string, content: string) => HeadElement` | `meta:<property>` |
| `twitter` | `(name: string, content: string) => HeadElement` | `meta:<name>` |
| `jsonLd` | `(data: unknown) => HeadElement` | none |
| `canonical` | `(url: string) => HeadElement` | `link:canonical` |
| `hreflang` | `(locale: string, url: string) => HeadElement` | `link:alternate:<locale>` |
| `feedLink` | `(title: string, url: string, type?: string) => HeadElement` | `link:feed:<url>`; `type` defaults to `"application/rss+xml"` |
| `buildArticleHead` | `(meta: ArticleMeta, canonicalUrl: string) => HeadElement[]` | canonical, `og:type`, `article:*`, JSON-LD |

`ArticleMeta`: `title`, and optional `description`, `author`, `published`, `modified`, `section`,
`tags`, `image`. The helpers are also reachable as `headPlugin.meta`, `headPlugin.og` and so on.

## Events

### Emits

None.

### Listens to

None.

## Depends on

- [site](/docs/web/plugins/site/): name, description, URL and `canonical()`.
- [router](/docs/web/plugins/router/): `toUrl()`, for canonical and alternate links.
- [i18n](/docs/web/plugins/i18n/), optional: `locales()` for hreflang and `ogLocale()`. Without
  it there is one locale and no `og:locale`.

## Example

```ts
import { createApp, defineRoutes, jsonLd, og, route } from "@moku-labs/web";
import { h } from "preact";

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

const app = createApp({
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    head: { titleTemplate: "%s · My Blog", twitterHandle: "@moku_labs" },
    router: { routes }
  }
});

const html = app.head.render(
  {
    path: "/about/",
    name: "about",
    params: {},
    head: {
      title: "About",
      elements: [
        og("og:title", "About the blog"),
        jsonLd({ "@context": "https://schema.org", "@type": "AboutPage" })
      ]
    }
  },
  {}
);

console.log(app.head.composeTitle({ title: "About" })); // "About · My Blog"
console.log(html.includes('<meta property="og:title" content="About the blog">')); // true
```

1. Same key as the generated `og:title`, so it replaces it.

```sh
$ bun scripts/head.ts
About · My Blog
true
```

- **`titleTemplate` must contain `%s`.** `createApp` throws `[web] head: titleTemplate must contain the "%s" token (replaced by the route title), received "…".`
- **`buildArticleHead` keeps `image` as given.** It does not resolve relative URLs. The route-level `image` does.
- **Use the helpers, not raw strings.** Elements are data. A string in `elements` is not a head tag.
- **On client navigation the head is not re-composed.** `spa` copies it from the fetched page, or only sets the title on the data path.

## Related

- [Head & SEO](/docs/web/guides/head/): the guide, with the build output.
- [build plugin](/docs/web/plugins/build/): feeds, sitemap and OG images.


# i18n

Source: https://moku-labs.com/docs/web/plugins/i18n/ · @moku-labs/web@2.4.11

> Default. The locale registry: locales, default locale, display names, og:locale map and a flat translation table.

## What it does

**Isomorphic default.** `i18n` holds the site's locales and translations as plain config. It has
no state, no events and no lifecycle work beyond a check while `createApp` runs. `router`,
`head`, `content` and `build` read it with `ctx.require(i18nPlugin)`.

## How it works

`createApp` checks two rules: `locales` is not empty, and `defaultLocale` is one of them. Every
lookup after that is total: a miss returns `undefined`, and `t()` falls back.

`t(locale, key)` resolves in a fixed order: the requested locale, then the default locale, then
the key itself. It never returns `undefined`.

Inside the framework, plugins that find no `i18n` use the same defaults it ships with: one
locale, `"en"`. Because `i18n` is a default plugin, that only matters for plugins you test
alone.

## Config

`pluginConfigs.i18n`.

| Option | Type | Default | Description |
|---|---|---|---|
| `locales` | `readonly string[]` | `["en"]` | Supported locales, in priority order. Must not be empty. |
| `defaultLocale` | `string` | `"en"` | The fallback locale, served at bare paths. Must be in `locales`. |
| `localeNames` | `Record<string, string>` | `{}` | Display names, e.g. `{ uk: "Українська" }`. |
| `ogLocaleMap` | `Record<string, string>` | `{}` | `og:locale` values, e.g. `{ en: "en_US" }`. |
| `translations` | `Record<string, Record<string, string>>` | `{}` | `locale → key → text`. |

## API

Mounted at `app.i18n`, reachable with `ctx.require(i18nPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `locales` | `() => readonly string[]` | The configured locales, in order. |
| `defaultLocale` | `() => string` | The fallback locale. |
| `isLocale` | `(x: string) => boolean` | Whether `x` is one of the locales. Case-sensitive. |
| `localeName` | `(locale: string) => string \| undefined` | The display name. |
| `ogLocale` | `(locale: string) => string \| undefined` | The `og:locale` value. |
| `t` | `(locale: string, key: string) => string` | The translation, with fallback. |

## Events

### Emits

None.

### Listens to

None.

## Depends on

Nothing.

## Example

```ts
import { createApp } from "@moku-labs/web";

const app = createApp({
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    i18n: {
      locales: ["en", "uk"],
      defaultLocale: "en",
      localeNames: { en: "English", uk: "Українська" },
      ogLocaleMap: { en: "en_US", uk: "uk_UA" },
      translations: {
        en: { "nav.home": "Home", "nav.about": "About" },
        uk: { "nav.home": "Головна" }
      }
    }
  }
});

console.log(app.i18n.t("uk", "nav.home")); // "Головна"
console.log(app.i18n.t("uk", "nav.about")); // "About": falls back to the default locale
console.log(app.i18n.t("uk", "nav.missing")); // "nav.missing": falls back to the key
console.log(app.i18n.localeName("uk"), app.i18n.ogLocale("en")); // "Українська" "en_US"
```

```sh
$ bun scripts/i18n.ts
Головна
About
nav.missing
Українська en_US
```

- **`defaultLocale` must be in `locales`.** `createApp` throws `[web] i18n.defaultLocale "en" is not in i18n.locales [uk].` with the fix on the next line.
- **An empty `locales` throws.** `[web] i18n.locales must contain at least one locale.`
- **hreflang is not here.** `i18n` owns `og:locale` values. `head` builds the hreflang links from `locales()` and the router.
- **The config is shallow-merged.** Passing `translations` replaces the whole table; it is not merged key by key.

## Related

- [i18n](/docs/web/guides/i18n/): the guide, with URLs per locale.
- [router plugin](/docs/web/plugins/router/): the `{lang:?}` slot.
- [content plugin](/docs/web/plugins/content/): locale files and fallback.


# router

Source: https://moku-labs.com/docs/web/plugins/router/ · @moku-labs/web@2.4.11

> Default. The route table: the typed route() builder, a specificity-sorted matcher, URL and file paths, the render mode.

## What it does

**Isomorphic default.** `router` owns the route table. You write routes with the `route()`
builder, register them in `pluginConfigs.router.routes`, and the router compiles them while
`createApp` runs. `build`, `head` and `spa` read the compiled table through its API: matching,
URLs, output files and the render mode.

## How it works

Each route compiles to two matchers built on a plain `RegExp`: one with the locale slot filled
by the configured locales, and one with the `{lang:?}` segment removed. A pathname is tried
against the first, then the second, which injects the default locale. That is how `/hello/`
resolves to `{ slug: "hello", lang: "en" }` and `/uk/hello/` to `{ lang: "uk", slug: "hello" }`.

The table is sorted by the number of dynamic segments, fewest first, with declaration order as
the tie-break. `{lang:?}` does not count, so adding a locale prefix never changes priority. The
same matching code runs at build and in the browser, so the two cannot disagree.

`createApp` validates the table and stops on: an empty map, a pattern that does not start with
`/`, unbalanced braces, or more than one `{lang:?}` segment.

Types are a call-site matter. `route()` captures the pattern as a literal, so `ctx.params` is
inferred, and `.load()` widens `ctx.data`. The route map in config is erased to
`Record<string, RouteDefinition>`; the build gets the full definitions back from `manifest()`.

## Config

`pluginConfigs.router`.

| Option | Type | Default | Description |
|---|---|---|---|
| `routes` | `RouteMap` | none | Route name → `route(...)`. An `import * as routes` namespace works. The only way to register routes. |

The render mode is not router config. It is the global `createApp({ config: { mode } })`, which
the router exposes as `mode()`.

## API

Mounted at `app.router`, reachable with `ctx.require(routerPlugin)`.

| Method | Signature | Description |
|---|---|---|
| `match` | `(pathname: string) => { params: Record<string, string>; route: RouteDefinition } \| null` | The most specific match, or `null`. |
| `toUrl` | `(routeName: string, params: Record<string, string>) => string` | Fills the pattern. Throws on an unknown name. |
| `entries` | `() => readonly TypedRoute[]` | Every route with `pattern`, `name`, `meta`, `toUrl`, `toFile`, `match`, most specific first. |
| `manifest` | `() => readonly RouteDefinition[]` | The full definitions with handlers, in declaration order. |
| `clientManifest` | `() => readonly ClientRoute[]` | `{ pattern, name, meta }` for each route, frozen and JSON-safe, most specific first. |
| `mode` | `() => "ssg" \| "spa" \| "hybrid"` | The global render mode. |

### Helpers

Plain functions with no `ctx`. They run before `createApp`. Exported from both entries, and
reachable as `routerPlugin.route`, `routerPlugin.defineRoutes`, `routerPlugin.createUrls`.

| Helper | Signature | Description |
|---|---|---|
| `route` | `<P extends string>(pattern: P) => RouteBuilder<RouteState<P>>` | The fluent builder. The returned object is itself a `RouteDefinition`. |
| `defineRoutes` | `<T extends RouteMap>(routes: T) => T` | Keeps the literal type of the map for IntelliSense. |
| `createUrls` | `<T extends RouteMap>(routes: T, defaultLocale?: string) => Urls<T>` | An app-free URL builder: `toUrl(name, params?)`, names typed to the map. Pass the default locale to get bare paths for it. |

The builder methods are listed in the [routing guide](/docs/web/guides/routing/#builder-methods).

## Events

### Emits

None.

### Listens to

None.

## Depends on

- [site](/docs/web/plugins/site/): the base URL.
- [i18n](/docs/web/plugins/i18n/), optional: the locales and the default locale. Without it the
  router compiles for `"en"`.

## Example

```ts
import { createApp, createUrls, defineRoutes, route } from "@moku-labs/web";
import { h } from "preact";

const routes = defineRoutes({
  home: route("/{lang:?}/").render(() => h("h1", null, "Home")),
  post: route("/{lang:?}/{slug}/")
    .render(ctx => h("h1", null, ctx.params.slug))
    .meta({ section: "blog" }),
  about: route("/about/").render(() => h("h1", null, "About"))
});

const app = createApp({
  pluginConfigs: {
    site: { name: "My Blog", url: "https://blog.dev", author: "Ada", description: "Notes." },
    i18n: { locales: ["en", "uk"], defaultLocale: "en" },
    router: { routes }
  }
});

console.log(app.router.match("/uk/hello/")?.params); // { lang: "uk", slug: "hello" }
console.log(app.router.match("/hello/")?.params); // { slug: "hello", lang: "en" }
console.log(app.router.toUrl("post", { lang: "uk", slug: "hello" })); // "/uk/hello/"
console.log(app.router.mode()); // "hybrid"
console.log(createUrls(routes, "en").toUrl("post", { lang: "en", slug: "hello" })); // "/hello/"
```

1. The same output as `app.router.toUrl`, with no app.

```sh
$ bun scripts/routes.ts
{ lang: "uk", slug: "hello" }
{ slug: "hello", lang: "en" }
/uk/hello/
hybrid
/hello/
```

- **Routes are registered once.** There is no `router.set()`. An app that builds routes at run time composes the map before `createApp`.
- **No routes, no router.** Without `pluginConfigs.router.routes`, every call throws `[web] router: routes not registered.`
- **`toUrl` throws on a typo.** An unknown name is an error, not an empty link.
- **Only `{lang:?}` matches when absent.** Another optional segment, such as `{page:?}`, matches only when it is present.
- **`meta` must be JSON.** It ships to the browser in `clientManifest()`. No functions, symbols or class instances.

## Related

- [Routing](/docs/web/guides/routing/): the guide, with every builder method.
- [i18n plugin](/docs/web/plugins/i18n/): where the locales come from.
- [spa plugin](/docs/web/plugins/spa/): matching in the browser.


# site

Source: https://moku-labs.com/docs/web/plugins/site/ · @moku-labs/web@2.4.11

> Default. The frozen site identity: name, URL, author, description, and canonical URLs.

## What it does

**Isomorphic default.** `site` holds four values that the rest of the framework reads: the site
name, the absolute base URL, the author and the description. It also joins paths into canonical
URLs. `router`, `head`, `build` and `deploy` depend on it.

## How it works

The four config fields are the whole model. The accessors read the frozen config and return
strings. There is no state and no event.

`createApp` validates the config right away: `name` must not be blank and `url` must be an
absolute `http` or `https` URL. The defaults are empty strings that only satisfy the type, so
every app passes real values, in the Node app and in the browser app.

`canonical(path)` joins a path to `url` without a double slash and keeps a trailing slash.
`canonical("/")` and `canonical("")` return the base URL.

## Config

`pluginConfigs.site`.

| Option | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | `""` | The site name: the fallback page title, feeds, the Pages project slug. Required. |
| `url` | `string` | `""` | The absolute base URL, e.g. `"https://blog.dev"`. Required. |
| `author` | `string` | `""` | The default byline, for feeds and article meta. |
| `description` | `string` | `""` | The default meta description and feed description. |

## API

Mounted at `app.site`, reachable with `ctx.require(sitePlugin)`.

| Method | Signature | Description |
|---|---|---|
| `name` | `() => string` | The site name. |
| `url` | `() => string` | The base URL. |
| `author` | `() => string` | The author. |
| `description` | `() => string` | The description. |
| `canonical` | `(path: string) => string` | The absolute URL of a path. |

## Events

### Emits

None.

### Listens to

None.

## Depends on

Nothing.

## Example

```ts
import { createApp } from "@moku-labs/web";

export const site = {
  name: "My Blog",
  url: "https://blog.dev",
  author: "Ada Lovelace",
  description: "Notes on computing."
};

const app = createApp({ pluginConfigs: { site } });

console.log(app.site.name()); // "My Blog"
console.log(app.site.canonical("/posts/hello/")); // "https://blog.dev/posts/hello/"
console.log(app.site.canonical("/")); // "https://blog.dev"
```

1. Keep it in one module and pass it to the Node app and the browser app.

```sh
$ bun scripts/build.ts
error: [web] site.url must be a valid absolute URL (http/https), received "blog.dev".
  Provide an absolute URL in pluginConfigs.site.url, e.g. "https://blog.dev".
```

The error is thrown by `createApp`, before any build work starts. Bun prints the source line
above it; it is left out here.

- **No usable defaults.** Without `pluginConfigs.site`, `createApp` throws `[web] site.name is required.` That includes the browser app.
- **`url` is the production origin.** Canonical links, `og:url`, absolute images, the sitemap and the feeds all start from it. A preview deploy still points them at production.
- **Errors have two lines.** The first says what is wrong, the indented second says how to fix it.

## Related

- [Head & SEO](/docs/web/guides/head/): where the identity ends up.
- [deploy plugin](/docs/web/plugins/deploy/): the project slug from `name`.


# spa

Source: https://moku-labs.com/docs/web/plugins/spa/ · @moku-labs/web@2.4.11

> Default. The client runtime: island hydration, intercepted navigation, head sync and a progress bar. Inert on Node.

## What it does

**Isomorphic default.** `spa` makes the static site live in the browser. It mounts islands onto
the server-rendered HTML, intercepts in-app links, swaps one page region without a full reload,
syncs the head and shows a progress bar. On Node it does nothing, so the same app definition
works in the build.

It is the one default plugin that owns a browser resource, so it is the one with `onStart` and
`onStop`.

## How it works

While `createApp` runs, `spa` builds a single kernel, validates its config, registers
`config.islands` and records the current URL. It looks for the optional `data` plugin with
`ctx.has("data")`.

`app.start()` boots the kernel in the browser: it attaches the navigation listeners and mounts
every `[data-island]` element. An island outside the swap region is persistent; one inside it is
created and destroyed with each page. `app.stop()` unmounts every island and detaches the
listeners.

A navigation takes the first path that works:

| Path | Used when | What happens |
|---|---|---|
| Data | `router.mode()` is not `"ssg"` and `data` is composed, or the route is client-only in `spa` mode | `router.match` → `data.at(path)` → the route's `render` into the swap region → islands re-mounted → title set |
| HTML-over-fetch | the data path is not available or fails | fetch the page, replace `swapSelector`, copy the head |
| Full load | the fetch fails | `location.href` |

The Navigation API is used where the browser has it, the History API otherwise. Clicks with a
modifier key, `target="_blank"`, other origins and links to static files are left to the
browser. Scroll positions are saved per page in `sessionStorage` and restored on back and
forward. The progress bar waits 150 ms before it shows.

## Config

`pluginConfigs.spa`. Every field is optional.

| Option | Type | Default | Description |
|---|---|---|---|
| `swapSelector` | `string` | `"main > section"` | The region replaced on navigation. Must be a valid CSS selector. |
| `viewTransitions` | `boolean \| TransitionMode` | `false` | `true` is `"crossfade"`, `false` is `"none"`. Modes: `"none"`, `"crossfade"`, `"slide"`, `"morph"`. A route's `.transition()` overrides it. |
| `scrollRestoration` | `"top" \| "preserve"` | `"top"` | Scroll after a forward navigation. A route's `.scroll()` overrides it. Back and forward always restore. |
| `progressBar` | `boolean` | `true` | The top progress bar. |
| `islands` | `IslandDef[]` | `[]` | Islands registered while `createApp` runs. |

## API

Mounted at `app.spa`, reachable with `ctx.require(spaPlugin)`. Every method is a no-op before
`app.start()` and on Node.

| Method | Signature | Description |
|---|---|---|
| `register` | `(island: IslandDef) => void` | Registers an island. A second island with the same name replaces the first and logs `spa:island-collision`. |
| `navigate` | `(path: string, options?: { scroll?, replace? }) => void` | Navigates through the swap pipeline. `replace: true` replaces the history entry. |
| `hardNavigate` | `(url: string) => void` | A real page load, for a boundary the SPA cannot swap: another layout, the auth split. |
| `current` | `() => string` | The current `pathname + search`. `""` on Node. |
| `island` | `<T>(name: string) => T \| undefined` | Another island's `api`, or `undefined`. |

The module-scope `navigate(path, options?)` and `hardNavigate(url)` from
`@moku-labs/web/browser` call the same kernel, for code with no app or island context.

## Events

### Emits

| Event | Payload | When |
|---|---|---|
| `spa:navigate` | `{ from: string; to: string }` | A navigation was intercepted and starts. |
| `spa:navigated` | `{ url: string }` | The swap finished and the new URL is active. |
| `spa:island-mount` | `{ name: string; el: Element }` | An island attached to an element. |
| `spa:island-unmount` | `{ name: string; el: Element }` | An island detached from an element. |

### Listens to

None.

## Depends on

- [router](/docs/web/plugins/router/): `match`, `mode`, `toUrl`.
- [head](/docs/web/plugins/head/): `composeTitle` for the data path.
- [data](/docs/web/plugins/data/), optional: `at(path)` for the data path.

## Example

```tsx
import { createApp, createIsland, dataPlugin, defineRoutes, route } from "@moku-labs/web/browser";

const routes = defineRoutes({
  home: route("/").render(() => <h1>Home</h1>),
  board: route("/board/{id}/")
    .render(ctx => <h1>Board {ctx.params.id}</h1>)
    .transition("slide")
});

const counter = createIsland("counter", {
  state: () => ({ count: 0 }),
  render: state => <button type="button">{state.count}</button>,
  events: { "click button": ctx => ctx.set(previous => ({ count: previous.count + 1 })) }
});

const app = createApp({
  plugins: [dataPlugin],
  config: { mode: "hybrid" },
  pluginConfigs: {
    site: { name: "Boards", url: "https://boards.dev", author: "Ada", description: "Kanban." },
    router: { routes },
    spa: {
      swapSelector: "main > section",
      viewTransitions: "crossfade",
      scrollRestoration: "top",
      islands: [counter]
    }
  }
});

await app.start();
app.spa.navigate("/board/42/");
console.log(app.spa.current());
```

1. Must exist in every page's layout.
2. Mounts islands and starts intercepting links. Does nothing on Node.
3. Slides, because the `board` route says so.

- **One app per page.** The teardown handles live at module scope. Two apps in one page share them.
- **`swapSelector` must match your layout.** A selector that matches nothing makes every navigation a full load. A syntax error throws `[web] spa.swapSelector is not a valid CSS selector` when the browser app is created; Node has no DOM to check it.
- **The layout is not re-applied.** On navigation only the swap region changes. `.layout()` runs at build only.
- **`load` does not run on the client.** The data path uses the JSON the build saved. A client-only route in `spa` mode renders with `ctx.data = {}`.
- **Use `@moku-labs/web/browser` for the client.** Its import graph has no Node module.

## Related

- [SPA navigation](/docs/web/guides/spa/): transitions, scroll, programmatic navigation, events.
- [Islands](/docs/web/guides/islands/): `createIsland` in full.
- [Data](/docs/web/guides/data/): the data path.


# API reference

Source: https://moku-labs.com/docs/web/api/ · @moku-labs/web@2.4.11

> Every export of @moku-labs/web and @moku-labs/web/browser, with signatures.

## Entries

| Import | Format | For |
|---|---|---|
| `@moku-labs/web` | ESM and CJS | The Node app: the build, the deploy, the CLI. Everything below. |
| `@moku-labs/web/browser` | ESM only | The client bundle. No Node module in its import graph. `env` reads `browserEnv()` with no config. |
| `@moku-labs/web/testing` | ESM only | Island test helpers: `mountIsland`, `renderIsland`. |

Signatures below are simplified for reading. The installed `dist/index.d.mts` is the source.

## createApp

```ts
function createApp<const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: {
  plugins?: ExtraPlugins;
  config?: { stage?: "production" | "development" | "test"; mode?: "ssg" | "spa" | "hybrid" };
  pluginConfigs?: { [pluginName: string]: Partial<PluginConfig> };
  onReady?: (ctx: AppCallbackContext) => void;
  onError?: (error: Error, ctx: AppCallbackContext) => void;
  onStart?: (ctx: AppCallbackContext) => void | Promise<void>;
  onStop?: (ctx: AppCallbackContext) => void | Promise<void>;
}): App;
```

Creates and initializes an app. It is synchronous: every plugin's config is resolved, every
`onInit` runs, and the frozen app is returned. Both entries export it, over the same five default
plugins (`site`, `i18n`, `router`, `head`, `spa`) and the core plugins `log` and `env`.

| Option | Default | Description |
|---|---|---|
| `plugins` | `[]` | Extra plugins, merged into the app and into its type. Order matters: a plugin comes after the plugins it depends on. |
| `config.stage` | `"production"` | Drafts are hidden only in `"production"`. |
| `config.mode` | `"hybrid"` | `"ssg"`, `"spa"` or `"hybrid"`. Read by plugins through `router.mode()`. |
| `pluginConfigs` | `{}` | Per-plugin overrides, keyed by plugin name, shallow-merged over the defaults. |
| `onReady`, `onError`, `onStart`, `onStop` | none | Lifecycle callbacks with the app context. |

The returned app:

| Member | What it is |
|---|---|
| `start()` | Runs every plugin's `onStart`. In the browser this boots `spa`. Call it once. |
| `stop()` | Runs every plugin's `onStop`. |
| `emit(event, payload)` | Emits a typed event. Only known names compile. |
| `require(plugin)`, `has(name)` | Plugin lookup. |
| `log`, `env` | The core plugin APIs. |
| `site`, `i18n`, `router`, `head`, `spa` | The default plugin APIs. |
| `<name>` | The API of every plugin in `plugins`, for example `app.build`, `app.content`. |

## createPlugin

```ts
function createPlugin<Name extends string, Config, State, Api, Deps, Events, Hooks, Helpers>(
  name: Name,
  spec: {
    config?: Config;
    depends?: Deps;
    createState?: (ctx: { global; config }) => State;
    events?: (register) => Events;
    api?: (ctx: PluginContext) => Api;
    hooks?: (ctx: PluginContext) => Hooks;
    helpers?: Helpers;
    onInit?: (ctx: PluginContext) => void;
    onStart?: (ctx: PluginContext) => void | Promise<void>;
    onStop?: (ctx: { global; config; state }) => void | Promise<void>;
  }
): PluginInstance<Name, Config, State, Api, Events> & Helpers;
```

Writes a plugin bound to this framework's config, events and core plugins. Never pass the type
parameters: they are inferred from the spec. `ctx` carries `global`, `config`, `state`, `emit`,
`require`, `has`, `log` and `env`. A plugin listed in `depends` makes its events available to
`hooks`, with typed payloads.

```ts
import { createPlugin, spaPlugin } from "@moku-labs/web/browser";

export const visitsPlugin = createPlugin("visits", {
  depends: [spaPlugin],
  config: { limit: 50 },
  createState: (): { urls: string[] } => ({ urls: [] }),
  events: register => ({
    "visits:full": register<{ count: number }>("The visit list reached its limit")
  }),
  hooks: ctx => ({
    "spa:navigated": ({ url }) => {
      ctx.state.urls.push(url);
      if (ctx.state.urls.length === ctx.config.limit) ctx.emit("visits:full", { count: ctx.state.urls.length });
    }
  }),
  api: ctx => ({ recent: () => [...ctx.state.urls] })
});
```

1. Plugin events are declared with `register`, never as a plain object.

## Routing

```ts
function route<P extends string>(pattern: P): RouteBuilder<RouteState<P>>;
function defineRoutes<T extends RouteMap>(routes: T): T;
function createUrls<T extends RouteMap>(routes: T, defaultLocale?: string): Urls<T>;

interface RouteBuilder<S extends RouteState> extends RouteDefinition {
  load<D>(loader: (ctx: LoadContext<S>) => D | Promise<D>): RouteBuilder<{ params: S["params"]; data: Awaited<D> }>;
  generate(handler: (ctx: GenerateContext) => S["params"][] | Promise<S["params"][]>): RouteBuilder<S>;
  render(handler: (ctx: RouteContext<S>) => VNode): RouteBuilder<S>;
  head(handler: (ctx: RouteContext<S>) => HeadConfig): RouteBuilder<S>;
  layout(component: (ctx: LayoutContext<S>, children: ComponentChildren) => VNode): RouteBuilder<S>;
  meta(meta: Record<string, unknown>): RouteBuilder<S>;
  transition(mode: "none" | "crossfade" | "slide" | "morph"): RouteBuilder<S>;
  scroll(mode: "top" | "preserve"): RouteBuilder<S>;
  toJson(handler: (ctx: RouteContext<S>) => unknown): RouteBuilder<S>;
  toFile(handler: (params: S["params"]) => string): RouteBuilder<S>;
}

interface Urls<T extends RouteMap> {
  toUrl<K extends keyof T & string>(name: K, params?: Record<string, string>): string;
}
```

| Context | Members |
|---|---|
| `GenerateContext` | `locale`, `require(plugin)`, `has(name)` |
| `LoadContext` | `params`, `locale`, `require(plugin)`, `has(name)` |
| `RouteContext` | `params`, `data`, `locale`, `meta`, `url(name, params?)` |

`params` is inferred from the pattern: `{x}` is required, `{x:?}` optional. Only `load` widens
`data`. `toJson` stores a serializer on the route; no built-in plugin reads it in 2.4.11. See
[Routing](/docs/web/guides/routing/).

## Islands and navigation

```ts
function createIsland<S extends object = object, A = unknown>(name: string, spec: IslandSpec<S, A>): IslandDef;

interface IslandSpec<S, A> {
  state?: (ctx: IslandContext<S>) => S;
  render?: (state: Readonly<S>, ctx: IslandContext<S>) => VNode | Node | string | null | void;
  events?: Record<string, (ctx: IslandContext<S>, event: Event, target: Element) => void>;
  api?: (ctx: IslandContext<S>) => A;
  onCreate?(ctx: IslandContext<S>): void;
  onMount?(ctx: IslandContext<S>): void;
  onNavStart?(ctx: IslandContext<S>): void;
  onNavEnd?(ctx: IslandContext<S>): void;
  onUnMount?(ctx: IslandContext<S>): void;
  onDestroy?(ctx: IslandContext<S>): void;
}

const lazyEmbed: IslandDef;
function navigate(path: string, options?: { scroll?: "top" | "preserve"; replace?: boolean }): void;
function hardNavigate(url: string): void;
function createChannel<T>(options: ChannelOptions<T>): Channel<T>;
```

`IslandContext` has `el`, `data`, `params`, `meta`, `locale`, `url`, `navigate`, `state`,
`set(patch)`, `flush()`, `cleanup(dispose)` and `island<T>(name)`. `createIsland` throws on an
empty name or an unknown hook. `lazyEmbed` activates the `::embed` facades of the content
pipeline. `navigate` and `hardNavigate` are no-ops before `app.start()`. See
[Islands](/docs/web/guides/islands/) and [SPA navigation](/docs/web/guides/spa/).

```ts
interface ChannelOptions<T> {
  url: (id: string) => string;
  parse?: (raw: string) => T | undefined; // default: JSON.parse, dropping frames that fail
  keepAlive?: { send: string; ignore?: string; everyMs?: number }; // everyMs default 30000
  reconnect?: { baseMs?: number; maxMs?: number } | false; // default 500 → 8000, doubling
  bufferUntilSeed?: boolean; // default false
  shouldReconnect?: (event: CloseEvent) => boolean;
}

interface Channel<T> {
  subscribe(id: string, handler: (message: T) => void): () => void;
  seed(id: string): void;
  deliverLocal(id: string, message: T): void;
  send(raw: string): void;
  current(): string | undefined;
  disconnect(): void;
}
```

## Head helpers

```ts
function meta(name: string, content: string): HeadElement;
function og(property: string, content: string): HeadElement;
function twitter(name: string, content: string): HeadElement;
function jsonLd(data: unknown): HeadElement;
function canonical(url: string): HeadElement;
function hreflang(locale: string, url: string): HeadElement;
function feedLink(title: string, url: string, type?: string): HeadElement;
function buildArticleHead(articleMeta: ArticleMeta, canonicalUrl: string): HeadElement[];

type HeadElement = { tag: "meta" | "link" | "title" | "script"; attrs?: Record<string, string>; children?: string; key?: string };
type ArticleMeta = { title: string; description?: string; author?: string; published?: string; modified?: string; section?: string; tags?: string[]; image?: string };
```

See [Head & SEO](/docs/web/guides/head/).

## Collections

```ts
function collectionUrl(baseUrl: string, collection: string, shard: string): string;
function loadCollectionShard<T>(baseUrl: string, collection: string, shard: string): Promise<T>;
```

`collectionUrl("/", "bank", "en/animals")` is `"/bank/en/animals.json"`. `loadCollectionShard`
fetches and parses that URL and throws on a non-OK response. Both are browser-safe.

## Content (Node)

```ts
function fileSystemContent(options: FileSystemContentOptions): ContentProvider;
function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
function GalleryTrack(props: GalleryProps): VNode;
```

`fileSystemContent` is the Node content provider; its options are on the
[content plugin page](/docs/web/plugins/content/). `EmbedFacadeButton` and `GalleryTrack` are the
default inner components of `::embed` and `::gallery`, exported to compose your own.

## Plugins

| Export | `app.<name>` | Kind | `/browser` |
|---|---|---|---|
| `sitePlugin` | `site` | default | yes |
| `i18nPlugin` | `i18n` | default | yes |
| `routerPlugin` | `router` | default; also `.route`, `.defineRoutes`, `.createUrls` | yes |
| `headPlugin` | `head` | default; also the eight head helpers | yes |
| `spaPlugin` | `spa` | default | yes |
| `contentPlugin` | `content` | opt-in | yes, for `ctx.require` and types |
| `dataPlugin` | `data` | opt-in | yes |
| `collectionPlugin` | `collection` | opt-in | no |
| `buildPlugin` | `build` | Node-only | no |
| `deployPlugin` | `deploy` | Node-only | no |
| `cliPlugin` | `cli` | Node-only | no |

The default plugins are always in the app. Their exports are for `ctx.require(...)`, `depends` and
types. Each plugin's config, API and events are on its own page under Plugins.

## Plugin APIs on app

| Member | Plugin |
|---|---|
| `app.site.name()` `url()` `author()` `description()` `canonical(path)` | [site](/docs/web/plugins/site/) |
| `app.i18n.locales()` `defaultLocale()` `isLocale(x)` `localeName(l)` `ogLocale(l)` `t(l, key)` | [i18n](/docs/web/plugins/i18n/) |
| `app.router.match(path)` `toUrl(name, params)` `entries()` `manifest()` `clientManifest()` `mode()` | [router](/docs/web/plugins/router/) |
| `app.head.render(route, data)` `siteHead(input)` `composeTitle(head)` | [head](/docs/web/plugins/head/) |
| `app.spa.register(island)` `navigate(path, options?)` `hardNavigate(url)` `current()` `island(name)` | [spa](/docs/web/plugins/spa/) |
| `app.content.loadAll(options?)` `load(slug, locale)` `renderMarkdown(md)` `invalidate(paths)` `articleToCard(a)` `contentDir()` | [content](/docs/web/plugins/content/) |
| `app.data.at(path)` `write(entries, options?)` `urlFor(path)` `fileFor(path)` | [data](/docs/web/plugins/data/) |
| `app.collection.at(c, s)` `write(entries, options?)` `urlFor(c, s)` `fileFor(c, s)` | [collection](/docs/web/plugins/collection/) |
| `app.build.run(options?)` `phases()` | [build](/docs/web/plugins/build/) |
| `app.deploy.run(options?)` `init(options?)` `getLastDeployment()` `projectName()` `createProject()` | [deploy](/docs/web/plugins/deploy/) |
| `app.cli.build(options?)` `update(changes, options?)` `serve(options?)` `preview(options?)` `deploy(options?)` | [cli](/docs/web/plugins/cli/) |

## Core plugins and env providers

Re-exported from `@moku-labs/common`.

| Export | Signature | `/browser` |
|---|---|---|
| `logPlugin` | core plugin, mounted at `ctx.log` and `app.log` | yes |
| `envPlugin` | core plugin, mounted at `ctx.env` and `app.env`: `get`, `require`, `has`, `getPublic`, `getPublicMap` | yes |
| `browserEnv` | `(options?: { globalKey?: string }) => EnvProvider`: reads `import.meta.env` and `globalThis.__ENV__` | yes, the default provider there |
| `processEnv` | `() => EnvProvider`: a copy of `process.env` | no |
| `dotenv` | `(path?: string) => EnvProvider`: a `.env` file, default `.env.local`, re-read on every load | no |
| `cloudflareBindings` | `() => EnvProvider`: `globalThis.__CLOUDFLARE_ENV__` per request | no |

On Node, `env` has no provider until you compose one:
`pluginConfigs: { env: { providers: [processEnv(), dotenv(".env")] } }`. The first provider with
a non-empty value wins.

## Types

Every plugin's types are grouped in a namespace, used as `Router.RouteContext`,
`Content.Article` and so on. The namespaces are type-only.

| Namespace | Main members | `/browser` |
|---|---|---|
| `Router` | `RouteBuilder`, `RouteState`, `RouteContext`, `LoadContext`, `GenerateContext`, `LayoutContext`, `RouteDefinition`, `RouteMap`, `Urls`, `RouterApi`, `RouterConfig`, `TypedRoute`, `ClientRoute`, `HeadConfig`, `TransitionMode`, `ScrollMode`, `ExtractRouteParams` | yes |
| `Head` | `Config`, `Api`, `HeadConfig`, `HeadElement`, `ArticleMeta`, `ResolvedRoute`, `HeadDefaults` | yes |
| `Spa` | `IslandSpec`, `IslandDef`, `IslandContext`, `IslandHooks`, `IslandEvents`, `IslandRender`, `RenderResult`, `NavigateOptions`, `SpaApi`, `SpaConfig`, `SpaEvents`, `PageData`, `TransitionMode`, `ScrollMode` | yes |
| `Content` | `Article`, `ArticleCard`, `Frontmatter`, `ComputedFields`, `ContentProvider`, `FileSystemContentOptions`, `MermaidDiagramOptions`, `LoadAllOptions`, `ContentEvents`, `Api`, `Config` | yes |
| `Data` | `DataConfig`, `DataEntry`, `DataProvider`, `DataWriteSummary`, `DataState` | yes |
| `Collection` | `CollectionConfig`, `CollectionShard`, `CollectionProvider`, `CollectionWriteSummary`, `CollectionState` | yes |
| `Build` | `Config`, `Api`, `RunOptions`, `BuildRunOverrides`, `BuildResult`, `BuildEvents`, `PhaseName`, `OgImageConfig`, `OgFont`, `RichOgInput` | no |
| `Deploy` | `Config`, `Api`, `DeployResult`, `DeployRunOptions`, `DeployInitOptions`, `InitResult`, `CreateProjectResult`, `DeployErrorCode`, `WorkflowTrigger` | no |
| `Cli` | `Config`, `Api`, `BuildOptions`, `BuildSummary`, `ServeOptions`, `PreviewOptions`, `UpdateOptions`, `DeployOptions`, `DeployOutcome`, `CliErrorCode`, `CliRenderer`, `Command` | no |
| `Env`, `Log` | the `env` and `log` types from `@moku-labs/common` | yes |

Also exported as types: `Channel`, `ChannelOptions`, `ChannelKeepAlive`, `ChannelReconnect` (both
entries) and `EmbedFacade`, `EmbedFacadeProps`, `EmbedOptions`, `GalleryComponent`,
`GalleryOptions`, `GalleryProps`, `GallerySlide` (Node entry).

```tsx
import type { Content, Router } from "@moku-labs/web/browser";

type CardContext = Router.RouteContext<Router.RouteState<"/{lang:?}/", Content.ArticleCard[]>>;

export function ArticleList(ctx: CardContext) {
  return (
    <ul>
      {ctx.data.map(card => (
        <li key={card.contentId}>
          <a href={card.url}>{card.title}</a>
        </li>
      ))}
    </ul>
  );
}
```

## Testing

```ts
function mountIsland<S extends object = object, A = unknown>(definition: IslandDef, options?: MountIslandOptions): IslandHandle<S, A>;
function renderIsland<S extends object>(render: IslandRender<S>, input: { state: S; ctx?: Partial<IslandContext<S>> }): RenderIslandResult;
```

`mountIsland` mounts one island through the real spa internals, with no `createApp`. Options:
`html`, `el`, `params`, `meta`, `data`, `locale`, `url`, `persistent`, `islands`. The handle has
`el`, `state`, `api`, `emitted`, `fire(spec)`, `dispatch(selector, event)`, `flush()`,
`settle()`, `navStart()`, `navEnd(route?)` and `unmount()`. `renderIsland` renders a `render`
function against fixture state and returns `host`, `html()`, `find(selector)` and `unmount()`.
Both need a DOM in the test runner.


# @moku-labs/worker

Source: https://moku-labs.com/docs/worker/ · @moku-labs/worker@0.20.9

> Cloudflare Workers backend. D1, KV, R2, Queues, DO — each one a plugin.

## Overview

`@moku-labs/worker` is the Cloudflare Workers backend for Moku. Every Cloudflare primitive is a
plugin that resolves its binding per request from the Worker `env`. A `server` plugin owns HTTP
routing and dispatch. The build-time `deploy` and `cli` plugins ship the Worker but stay out of the
runtime bundle.

- **Every primitive is a plugin.** KV, D1, R2, Queues and Durable Objects. Add only what you use;
  the rest tree-shakes away.
- **`env` is a call argument, never state.** One isolate serves many requests at once, so a
  binding lives on the call stack and cannot leak between them.
- **Not an ORM, not a router framework.** Thin typed wrappers over the real Cloudflare APIs.

| Plugin | What it does |
| --- | --- |
| `bindings` | Resolves bindings from the per-request `env`. A default. |
| `server` | HTTP routing and request dispatch. A default. |
| `kv`, `d1`, `storage`, `queues`, `durableObjects` | KV, D1, R2, Queues and Durable Objects. |
| `deploy`, `cli` | Provision, generate the wrangler config, deploy. Node only. |

## Install

```sh
bun add @moku-labs/worker
bun add -d @cloudflare/workers-types
```

## Quick start

Declare the routes as data. `bindings` and `server` are defaults: you never list them.

```ts
import { createApp, endpoint } from "@moku-labs/worker";

export const app = createApp({
  config: { name: "my-api", compatibilityDate: "2026-06-17" },
  pluginConfigs: {
    server: {
      endpoints: [
        endpoint("/health").get(() => new Response("ok")),
        endpoint("/api/data/{lang:?}").get(({ params }) =>
          Response.json({ lang: params.lang ?? "en" })
        ),
        endpoint("/users/{userId}").get(({ params }) => new Response(`user=${params.userId}`))
      ]
    }
  }
});
```

1. {lang:?} is optional, typed string | undefined.

The Worker entry is yours. It hands every request to `app.server`:

```ts
import { app } from "./app";

export default {
  fetch: (request: Request, env: Record<string, unknown>, ctx: ExecutionContext) =>
    app.server.handle(request, env, ctx)
} satisfies ExportedHandler;
```

A request to `/api/data/fr` returns `{ "lang": "fr" }`. An unmatched path returns `404`.

> **Warning**
>
> Do not list a default plugin again. `plugins` appends after `[log, env, bindings, server]`, so a
> second `bindingsPlugin` is a duplicate name and the kernel refuses to start. Configure a default
> through `pluginConfigs` instead.

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/room

Source: https://moku-labs.com/docs/room/ · @moku-labs/room@0.8.9

> Couch multiplayer. One screen, phones as controllers, no server.

## Overview

`@moku-labs/room` is a Moku framework for local multiplayer. A shared screen hosts the game state,
phones join by scanning a QR code, and everything flows over direct WebRTC DataChannels on the LAN.
No accounts, no lobby servers, no relay for gameplay.

- **Couch multiplayer, no server.** One shared screen hosts. Phones join by QR and talk to it
  directly over WebRTC.
- **The host owns the truth.** The stage validates controller intents, owns the game state and
  sends snapshots and deltas back. Phones render a read-only replica.
- **Two planes, never crossed.** Gameplay rides the typed wire. Only coarse `room:*` lifecycle
  rides Moku events.

> **Warning**
>
> Room is strictly peer-to-peer, with no TURN by default. On networks that isolate clients the
> connection cannot be made, and the app gets `room:network-warning`. The design target is the home
> Wi-Fi, with everyone in one room.

## Install

```sh
bun add @moku-labs/room @moku-labs/core @moku-labs/common
```

## Quick start

The stage is the shared screen. Add the host facade `stagePlugin` and a game plugin that depends on
it, so the `room:*` events are typed in its hooks.

```ts
import { createApp, createPlugin, inMemory, stagePlugin } from "@moku-labs/room";

const gamePlugin = createPlugin("game", {
  depends: [stagePlugin],
  hooks: ctx => ({
    "room:peer-joined": ({ peerId }) => ctx.log.info("game:joined", { peerId }),
    "room:network-warning": ({ reason }) => ctx.log.warn("game:network", { reason })
  })
});

const app = createApp({
  plugins: [stagePlugin, gamePlugin],
  pluginConfigs: { transport: { signaling: inMemory(), iceServers: [] } }
});
await app.start();

const { code, joinUrl } = app.stage.createRoom();
console.log(`Join ${code} at ${joinUrl}`);

app.stage.onIntent("score", (_payload, peerId) => {
  app.stage.mutate("scores", draft => ({ ...draft, [peerId]: Number(draft[peerId] ?? 0) + 1 }));
});
```

1. In-process signaling for a local try-out. The default is publicRendezvous().
2. Synchronous: a 6-character code and the join URL.

A phone is the same framework with `controllerPlugin`: `await app.controller.joinRoom(code)`, then
`app.controller.intent("score", {})`.

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/system

Source: https://moku-labs.com/docs/system/ · @moku-labs/system@0.3.7

> One system API, two runtimes. A missing capability is data, not a throw.

## Overview

`@moku-labs/system` gives Moku apps system capabilities behind one API: `store`, `tray`, `notify`,
`clipboard`, `deep-link`, `lifecycle`, `back`, `haptics` and `keepAwake`. A Tauri provider runs when
the native shell is detected, a web provider otherwise. Your code never branches on the runtime.

- **One codebase, web and native.** Each capability picks its provider once at startup.
- **A degraded capability is data, never a throw.** Every method returns `SystemResult<T>`:
  `{ ok: true, value }` or `{ ok: false, reason }`.
- **Zero-leak bundles.** Plugins live at subpath exports, and the `@tauri-apps/*` packages are
  optional peers loaded only in the native shell.

| `reason` | Meaning | What to do |
| --- | --- | --- |
| `unsupported` | The capability does not exist here, for good. | Hide the feature. |
| `denied` | The user or platform refused permission. | Explain, or ask again on purpose. |
| `unavailable` | It cannot work right now. | Retry later. |
| `error` | The provider threw; the message is kept. | Log it and recover. |

## Install

```sh
bun add @moku-labs/system @moku-labs/core @moku-labs/common
```

## Quick start

```ts
import { createApp } from "@moku-labs/system";
import { storePlugin } from "@moku-labs/system/store";

const system = createApp({
  plugins: [storePlugin],
  pluginConfigs: { store: { name: "my-app" } }
});

await system.start();

const result = await system.store.get<number>("count");
if (result.ok) {
  console.log(result.value ?? 0, `(from the ${result.provider} provider)`);
} else if (result.reason === "unsupported") {
  // hide the feature: this environment will never support it
} else {
  console.warn(result.reason, result.message);
}

await system.stop();
```

1. Plugins come from subpaths, never from the root.

To build the native shell, compose the same capabilities in
[`@moku-labs/native`](/docs/native/). It generates the Tauri permissions from that list.

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/native

Source: https://moku-labs.com/docs/native/ · @moku-labs/native@0.3.13

> Compose system plugins, get installers for 5 targets.

## Overview

`@moku-labs/native` is the node-only native packager of the Moku family. It wraps Tauri 2 end to
end: it generates a gitignored Tauri project, generates the permission surface from the system
plugins your app composed, and drives `tauri build` for macOS, Windows, Linux, iOS and Android. It
ships nothing inside your app.

- **The composition is the permission surface.** Declare `{ name: "notification" }` once, and the
  registry resolves the dependencies, the Rust init and the capability JSON.
- **Generated, gitignored, regenerable.** `.moku/tauri/` is build output, not source. Delete it and
  the next build writes it again.
- **Secrets stay in env vars.** Config holds the names of env vars only. `doctor` checks that they
  exist without reading them.

## Install

```sh
bun add @moku-labs/native @moku-labs/core @moku-labs/common
```

A real `node` binary on `PATH` is required: `@tauri-apps/cli` does not run under Bun.

## Quick start

A native app is its own `createApp`, next to your web app:

```ts
import { createApp } from "@moku-labs/native";

export const native = createApp({
  config: {
    app: { name: "MyApp", identifier: "com.example.myapp" },
    web: {
      build: "bun run build",
      devCommand: "bun run dev",
      devUrl: "http://localhost:5173",
      dist: "dist"
    },
    system: [{ name: "store" }, { name: "deep-link" }],
    capabilities: { "deep-link": { mode: "scheme", scheme: "myapp" } },
    targets: ["macos", "ios"]
  }
});
```

1. No icon yet: a placeholder is generated.
2. Default: the host's own desktop target. Mobile is opt-in.

One thin script per verb:

```ts
import { native } from "../src/native";

await native.start();
await native.cli.build({ target: "macos" }); // installers land in dist-native/macos/
await native.stop();
```

> **Warning**
>
> Add `.moku/` and `dist-native/` to `.gitignore`. The generated Tauri project is never committed.

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/game

Source: https://moku-labs.com/docs/game/ · @moku-labs/game@0.15.89

> A 2D puzzle engine where the game is a graph.

## Overview

`@moku-labs/game` is a 2D puzzle engine where the game is a graph, and the screen is just an
opinion about it. You write small nodes and edge tables. The engine runs them, saves on the edges
and replays the whole game without a screen. It ships no genre rules.

- **The game is a graph.** Flows are edge tables. Nodes are small functions with plain `await`
  bodies. One node is active at a time.
- **State commits only on edges.** A node works on drafts. A node that throws changes nothing.
- **Deterministic by construction.** Time is an input named `now`. Randomness is a saved `rng`
  stream. A lint rule refuses `Date.now` and `Math.random` in game logic.

## Install

```sh
bun add @moku-labs/game pixi.js
```

Bun only, ESM only. `pixi.js` is a peer dependency. Screens are `.tsx`, so a game sets
`"jsxImportSource": "@moku-labs/game"`.

## Quick start

A dice game: one rest node, one working node, one flow. `defineGame` binds the helpers to the
types of the game.

```ts
import { defineGame, type } from "@moku-labs/game";

const { defineNode, defineFlow } = defineGame<{
  player: { coins: number };
  session: { rolls: number };
  assets: string;
  strings: Record<string, unknown>;
}>();

const home = defineNode({ outcomes: { roll: type() }, rest: true, checkpoint: true });

const roll = defineNode({
  outcomes: { done: type() },
  run: ({ player, session, rng, out }) => {
    player.coins += rng.stream("dice").range(1, 6);
    session.rolls += 1;
    return out.done();
  }
});

export const mainFlow = defineFlow("main", {
  nodes: { home, roll },
  start: "home",
  edges: { home: { roll: "roll" }, roll: { done: "home" } }
});
```

1. A rest node: the graph waits here for the player.
2. The drafts commit on this edge.

The game itself is one data object in `index.ts`:

```ts
import { defineGameApp } from "@moku-labs/game/app";
import { mainFlow } from "./flow";

export default defineGameApp({
  flow: mainFlow,
  safeNode: "home",
  player: { coins: 0 },
  session: { rolls: 0 }
});
```

Serve it with hot reload:

```sh
bunx moku-game dev
```

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/editor

Source: https://moku-labs.com/docs/editor/ · @moku-labs/editor@0.10.19

> Devtools for a running game: flow, state, render.

## Overview

`@moku-labs/editor` is the devtools for a running `@moku-labs/game`. One tools page shows the
flow, the state, the render and the files of the live game, and lets you change them. It is a dev
dependency: nothing of it ships in a release build.

- **One registry, every surface.** The overlay, the tools page, MCP and a test read the same
  sources and commands.
- **Doors, not hooks.** The editor touches the game only through `@moku-labs/game/inspect` and
  `@moku-labs/game/control`. No private hooks, no engine fork.
- **Edits keep the game state.** A save reloads the game page and restores the bookmark taken just
  before it.

## Install

```sh
bun add -d @moku-labs/editor @moku-labs/game typescript
```

## Quick start

In a moku-game folder, the one with `index.ts` and `config.ts`, run the editor:

```sh
bunx moku-editor --root .
```

It prints the two pages:

```text
Game   http://127.0.0.1:3000/
Tools  http://127.0.0.1:3000/__editor/
Root   /home/dev/timber
```

The engine writes the dev page with the editor's agent on it, so the game needs no HTML file and
no dev entry.

| Flag | Default | What it does |
| --- | --- | --- |
| `--root`, `-r` | `.` | The game folder. |
| `--port`, `-p` | `3000` | Port on `127.0.0.1`. `0` picks a free port. |
| `--no-hmr` | hot reload on | Serves the game without hot reload. |
| `--packed` | loose files | Serves the packed assets of `moku-game pack`. |

> **Note**
>
> The server binds `127.0.0.1` only and checks Host, Origin and a per-start token. It reads and
> writes files only inside the project root.

## Use with Claude Code

`moku-editor mcp` is a stdio MCP server. Register it from the game folder, and Claude can read the
game, run commands and take screenshots:

```sh
claude mcp add moku-editor -- bunx moku-editor mcp
```

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/ai

Source: https://moku-labs.com/docs/ai/ · @moku-labs/ai@0.16.13

> Build system for AI assets. kill -9 is a supported workflow.

## Overview

`@moku-labs/ai` is a build system for AI-generated assets. You declare what should exist in a
`*.moku.yaml` build file. The runner drives whichever provider implements the task, checks every
dollar against a budget, and journals every state change to crash-safe SQLite. It is not an SDK
wrapper and not a job queue.

- **`kill -9` is a supported workflow.** Every run, item and attempt change is a committed write.
  Run again and it resumes where it stopped.
- **Budget-gated by construction.** One atomic transaction checks the projected spend against
  `--max-cost` before anything is billed.
- **Incremental by default.** Every item has an artifact key. A done artifact is reused for $0.

Tasks: `voiceover`, `translate`, `prompt-gen`, `image`, `video`, `music`, `sfx`, `sprite`, `asset`.
Providers: `elevenlabs`, `openai`, `codex`, `claude`, `fal`, `apimodels`, `ark`.

## Install

```sh
bun add @moku-labs/ai @moku-labs/core @moku-labs/common
```

Providers read their API keys from the environment when a request runs, or from `.env.local` in
the working directory. Estimates and validation need no key.

## Quick start

Declare a build file:

```yaml
version: 1
name: hello
items:
  - task: voiceover
    input:
      text: "Hello, world!"
      voice: "21m00Tcm4TlvDq8ikWAM"
  - task: translate
    provider: openai
    input:
      text: "Hello, world!"
      targetLang: es
```

Estimate it, then run it under a budget ceiling:

```ts
import { createApp } from "@moku-labs/ai";

const app = createApp({});
await app.start();

const { totalUsd } = await app.runner.estimate({ files: "hello.moku.yaml" });
const result = await app.runner.run({ files: "hello.moku.yaml", maxCostUsd: totalUsd * 1.2 });

console.log(result.status, result.totals);
await app.stop();
```

1. The budget gate refuses an item that would cross the ceiling.

Or from the shell. The package ships the `moku` bin:

```sh
moku new hello        # scaffold hello.moku.yaml and its JSON Schema
moku validate         # compile every build file
moku estimate         # cost per task and provider, no key needed
moku run --max-cost 5 # run; Ctrl-C pauses, moku run resumes
```

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```


# @moku-labs/ci

Source: https://moku-labs.com/docs/ci/ · @moku-labs/ci@1.5.7

> One CI and release pipeline. Tokenless publishing.

## Overview

`@moku-labs/ci` is one CI and release pipeline for every Moku package: reusable GitHub workflows
pinned by tag, plus the `moku-release` CLI that installs them into a project. A project keeps two
short workflow files and a few scripts. Everything else lives in one place.

- **One copy of the pipeline.** Every package calls the same reusable workflows from `@v1`. A fix
  lands once and reaches every project.
- **Scripts are the interface.** The workflows call `bun run lint`, never a tool directly. A
  project with special needs changes its own script.
- **No tokens.** npm Trusted Publishing with `id-token: write`. There is no `NPM_TOKEN` anywhere.

| Who releases | Version |
| --- | --- |
| a merge to `main` | patch, always |
| a person | minor |
| a person, for a milestone | major |

## Install

```sh
bun add -d @moku-labs/ci
bun run release:setup
```

`release:setup` writes the two workflow files and the Dependabot files, adds the missing scripts,
registers the trusted publisher and applies the branch ruleset. Run it again any time: it only does
what is still missing.

> **Warning**
>
> Two steps are yours alone, because the CLI never handles a credential: `gh auth login` and
> `npm login`.

## Quick start

The CI caller is a thin file. All logic lives in `moku-labs/ci`:

```yaml
name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  ci:
    uses: moku-labs/ci/.github/workflows/package-ci.yml@v1
```

Every pull request then reports four checks: `ci / lint`, `ci / types`, `ci / test` and
`ci / build`. Check the setup any time:

```sh
bun run release:doctor
```

## Start with Claude

Describe what you want. The conductor picks the packages.

```text
Build a blog with tags and an RSS feed on @moku-labs/web
```

```text
Add a D1-backed comments API with @moku-labs/worker
```

```text
Make a couch quiz game: TV shows questions, phones answer
```

```text
Ship this app to macOS and iOS
```