Module System

Hook zones

Zones are named injection points in the layout where modules contribute UI. The framework Base layout renders two built-in zones. Apps can define more.

// Rendered in Base.astro as:
<Hook zone="stnd:base" />

// Rendered in Base.astro as:
<Hook zone="stnd:client" hydrated={true} />

Custom zones

Apps can define their own zones. Just render a <Hook> in your layout and contribute to it from any module.

---
import Hook from "@stnd/core/Hook";
---

<aside>
  <Hook zone="sidebar" />
</aside>

// modules/weather/index.module.js
export default {
  id: "weather",
  name: "Weather Widget",
  hooks: {
    "sidebar": ["./WeatherCard.astro"],
  },
};

The system layer

Every page rendered with Base.astro includes a system layer that persists across navigations. Gold Standard modules inject their UI here automatically — you never import Toast, Confetti, or Lab manually.

<!-- Inside @stnd/layout/Base.astro -->
<div id="standard-os" transition:persist="standard-os">

  <!-- Zero-JS: Toast container, Confetti script -->
  <Hook zone="stnd:base" />

  <!-- Hydrated: Lab inspector, app extensions -->
  <Hook zone="stnd:client" hydrated={true} />

</div>

Gold Standard modules

Every @stnd/core site ships with these modules by default. No configuration needed — they're loaded automatically. Opt out of any module with moduleExclude.

System UI

Styles & Fonts

Client Enhancements

SEO & Web Standards

Opt out

Don't want confetti? Exclude it in your Astro config. The module is skipped entirely — no code, no styles, no scripts.

// astro.config.mjs
import standard from "@stnd/core";

export default defineConfig({
  integrations: [
    standard({
      moduleExclude: [
        "@stnd/modules/confetti",     // No celebration
        "@stnd/modules/lab",          // No debug inspector
      ],
    }),
  ],
});

Add your own modules

Load additional @stnd/* modules or any npm package that exports a module manifest.

// astro.config.mjs
import standard from "@stnd/core";

export default defineConfig({
  integrations: [
    standard({
      moduleLoad: [
        "@stnd/modules/rss",          // Add RSS feed
        "@stnd/modules/humans",       // Add humans.txt
        "@stnd/fonts/cargo-diatype",  // Add a typeface
      ],
    }),
  ],
});

App-level modules are discovered automatically from your modules/ folder — no registration needed.

Manifest reference

Every key a module manifest can declare. All keys are optional except id and name.

Hook entry formats

Each hook zone accepts an array of entries. Entries can be strings (shorthand) or objects with ui, action, meta, and trigger.

hooks: {
  "stnd:base": [
    // String shorthand — just a path, no metadata
    "./MyComponent.astro",
  ],

  "stnd:client": [
    // Object — full control
    {
      ui: "./MyWidget.svelte",       // The component to render
      meta: { "client:load": true }, // Props / hydration directives
    },
  ],

  "launcher:view": [
    // Launcher view — ui + trigger + meta
    {
      ui: "./views/SearchView.svelte",
      trigger: "::search",
      meta: {
        title: "Search",
        icon: "ph:magnifying-glass",
        size: { width: "standard", height: "standard" },
      },
    },
  ],

  "launcher:action": [
    // Action handler — points to a JS file
    {
      action: "./actions/navigation.js",
      meta: { label: "Navigation" },
    },
  ],
}

Full example

A complete module manifest using every available key.

// modules/upload-system/index.module.js
export default {
  id: "upload-system",
  name: "Upload System",
  description: "Global drag and drop zone for file uploads.",

  dependencies: ["root"],

  routes: [
    { path: "/uploads", entrypoint: "./routes/index.astro" },
  ],

  styles: ["./styles/dropzone.scss"],

  scripts: ["./client/upload-progress.js"],

  middleware: [
    { entrypoint: "./middleware.ts", order: 10 },
  ],

  actions: "./actions.ts",

  hooks: {
    "stnd:client": [
      {
        ui: "./GlobalDropZone.svelte",
        meta: { "client:load": true },
      },
    ],
  },

  config: {
    maxUploadSize: "10MB",
  },

  aliases: {
    "@uploads": ".",
  },
};

Module lifecycle

Modules are loaded once during astro:config:setup and their contributions are wired into the build pipeline.

1. Discover — Scans modules/ for *.module.js files and resolves moduleLoad packages.
2. Import — Dynamic-imports each manifest. Validates that every module has a unique id.
3. Sort deps — Builds a dependency graph and produces a topological load order. Circular dependencies throw.
4. Wire — Routes are injected via injectRoute. Styles and scripts become virtual modules. Middleware is registered. Hook zones are populated. Aliases are set.
5. Build — Astro takes over. Virtual modules are resolved. Components render. Everything is bundled.

Import rules

Modules follow strict import boundaries. This keeps the architecture clean and ensures any module can be deleted without breaking others.

// ✓ Good — importing from @stnd packages
import Icon from "@stnd/icon/Icon.svelte";
import { slugify } from "@stnd/utils";

// ✓ Good — importing from the core module
import Note from "@modules/core/models/Note";

// ✗ Bad — cross-importing between feature modules
import Thing from "@modules/upload-system/Thing";  // NO

Quick reference