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 underhooks:in itsindex.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() |
hook-kind-mismatchA 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:
- Explicit return required: Each handler receives the current value and must explicitly return the next one. To leave the value untouched, return it as-is (
return descriptor;). - Fail-loud design: There is no implicit pass-through on
undefined— a handler that forgets to return fails loudly so broken transforms are caught immediately.
// 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 /> }
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
- SSR vs. Client Split (
server: true): Mark any logic handler that touches server-only resources (databases, secrets, API keys) withserver: true. This strips the handler from the client bundle ofvirtual:stnd/hookswhen client consumers (such as@stnd/launcher) importrunHookorrunPipeline. - Logic Hooks Only (
hook-server-flag-ignored): Settingserver: trueon alauncher:*or*:actionentry is a build-time fatal error becausevirtual:stnd/componentshas no SSR/client split. - Failure Isolation: Both
runHookandrunPipelinewrap each handler in an error boundary. A throwing handler is logged with its module ID and skipped so one broken module cannot abort sibling handlers or crash the page.
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:
- Create the
.sveltefile (inpackages/account/views/or your own module’sviews/), exporting a component withlet { close, back, setSize } = $props(). - Register it in your module’s
index.module.js:hooks: { "launcher:view": [ { trigger: "::view-id", component: "./views/View.svelte", meta: { title, icon, size } }, ], } - Wire a trigger from any element:
data-launcher-view="::view-id", or calllauncherView("::view-id")directly.