stnd.build

Hooks & Extension Points

How modules render into shared zones and call into each other, without ever importing one another. Plus every hook zone the framework itself ships with.

Rule of thumb: Modules never import each other (Law #4). Instead, a module registers entries under hooks: in its index.module.js, and consumers render UI zones or invoke logic pipelines by hook name.

Quick Start (TL;DR)

Mechanism Registration in index.module.js Consumer Call Return / Behavior
UI Zone "stnd:base": ["./Toast.astro"] <Hook zone="stnd:base" /> Renders all registered .astro / .svelte components in load order
Fan-out Hook "my:event": [{ action: "./on-event.js" }] await runHook("my:event", ctx) Calls every handler and returns an array of all results
Sequential Pipeline "note:render": [{ action: "./gate.ts", server: true }] await runPipeline("note:render", val, ctx) Threads val through each handler in sequence; each must return the next value
Launcher Extension "launcher:action": ["./actions.js"] extensions["launcher:action"] Registers command palette actions or full-screen views in @stnd/launcher

Native Framework Hook Zones

Hook Name Kind Provided By Purpose
stnd:base UI Zone @stnd/layout (Base.astro) Global server-rendered markup injected before </body> (toasts, overlays, analytics)
stnd:client UI Zone @stnd/layout (Base.astro) Client-hydrated islands and behavior scripts (@stnd/client, @stnd/workshop, @stnd/launcher)
launcher:view UI / Action @stnd/launcher Full-screen Svelte 5 views inside the Cmd+K Launcher
launcher:action Action @stnd/launcher Command palette action providers
astro:config:setup Astro Lifecycle @stnd/core Build-time Astro lifecycle hook forwarded from module manifests

How Hook Classification Works

Modules never import each other directly. Instead, they publish entries to a named hook in index.module.js, and consumers either mount that zone or invoke its handlers by name. Except for the astro:* prefix (reserved for Astro’s build lifecycle), any hook name is a shared contract your modules can invent as needed.

Every entry under a module’s hooks: key is classified automatically into one of two pools:

Entry Pattern Classified Pool Virtual Module How Consumers Read It
.astro, .svelte, .md (or { ui: "..." }) UI Zone virtual:stnd/components Rendered via <Hook zone="..." />
launcher:* prefix or *:action suffix (any file type) UI / Action Zone virtual:stnd/components Read as callable handlers or views via extensions[zone]
.js, .ts (or { action: "..." }) Logic Hook virtual:stnd/hooks Executed via runHook() or runPipeline()
Build-Time Invariant: hook-kind-mismatch

A hook name must classify into the same pool everywhere it is registered. Because UI zones (virtual:stnd/components) and logic hooks (virtual:stnd/hooks) compile into separate virtual modules, registering the same hook name with both kinds across two modules throws a build-time fatal error (hook-kind-mismatch).

Render into a UI zone

hooks: {
  "stnd:base":   ["./components/Toast.astro"],
  "stnd:client": [{ ui: "./Drawer.svelte", meta: { "client:load": true } }],
}

Zones are rendered with <Hook zone="stnd:base" /> anywhere in your layouts. Multiple modules can contribute to the same zone — their components are rendered sequentially in load order. To let a single module take over rendering conditionally, use a logic pipeline (runPipeline) instead.

Call into every module at once — runHook

Fans a call out to every module registered under that name and collects their results into an array. Use it when gathering independent contributions across modules.

// modules/blog/index.module.js
hooks: {
  "astro:build:done": [{ action: "./hooks/generate-feed.js" }],
}
// consuming the hook
import { runHook } from "virtual:stnd/hooks";
const results = await runHook("astro:build:done", buildContext);

Thread a value through every module — runPipeline

Threads a single value through every registered handler in sequence. Use it when a route wants to ask “here is what I am about to render — does any module want to override it?” without naming those modules directly:

// apps/stnd.gd/modules/password-gate/index.module.js — a real, live example
hooks: {
  "note:render": [{ action: "./server/note-gate.ts", server: true }],
}
// note-gate.ts
export default async function resolveNoteGate(descriptor, ctx) {
  const isLocked = Boolean(ctx.note?.isPasswordProtected && !ctx.isOwner);
  if (!isLocked) return descriptor; // pass through unchanged
  return { ...descriptor, override: true, Component: PasswordGate, props: {/* ... */} };
}
---
// the consuming route — never imports password-gate by name
import { runPipeline } from "virtual:stnd/hooks";
const result = await runPipeline("note:render", { override: false, Component: null, props: {} }, { note, isOwner });
const GateComponent = result.Component; // dynamic Astro tags need a capitalized local const
---
{ result.override && GateComponent ? <GateComponent {...result.props} /> : <RealContent /> }
Pipeline Arbitration: First Claim Wins

Multiple modules (e.g. password-gate, paywall, region-lock) can register under note:render without changing the route. Because runPipeline runs handlers sequentially without built-in arbitration, check whether an earlier handler already claimed the descriptor (if (descriptor.override) return descriptor;) before overwriting it.

Server-Only Isolation & Error Handling

Native hooks

These are the hook names the framework’s own gold standard modules ship
with — the ones every Standard site has access to unless the module is
excluded via moduleExclude. Everything else (note:render, your own
app’s hooks) is a convention your own modules invent as they go.

Hook Kind Who registers it What lands there
stnd:base UI zone @stnd/modules/toast, @stnd/modules/confetti Static Astro components — no hydration. Rendered via <Hook zone="stnd:base" /> in StndInit.astro.
stnd:client UI zone @stnd/modules/launcher, @stnd/modules/workshop Hydrated Svelte components — client:load islands. Rendered via <Hook zone="stnd:client" hydrated /> in StndInit.astro.
launcher:view UI/action @stnd/account (and any app module) A full Svelte view registered into the command palette, triggered by a ::trigger string — see @stnd/launcher.
launcher:action UI/action @stnd/account (and any app module) A palette command’s metadata + handler, run via runHook("launcher:action", ...) when the launcher fans out a search or command.

Add a view to the launcher

The most common reason to reach for a hook — registering a new palette
view:

  1. Create the .svelte file (in packages/account/views/ or your own module’s views/), exporting a component with let { close, back, setSize } = $props().
  2. Register it in your module’s index.module.js:
    hooks: {
      "launcher:view": [
        { trigger: "::view-id", component: "./views/View.svelte", meta: { title, icon, size } },
      ],
    }
    
  3. Wire a trigger from any element: data-launcher-view="::view-id", or call launcherView("::view-id") directly.