stnd.build

Building a Module

Recipes for the day-to-day — routes, styles, config, dependencies, disabling a module — plus the full manifest key reference.

Quick Start (TL;DR)

Every feature in a Standard application is a self-contained vertical slice under modules/<name>/ with an index.module.js manifest (auto-discovered at build time):

modules/blog/
├── index.module.js       # Manifest (id, routes, hooks, styles, config)
├── routes/
│   ├── index.astro       # Route template (no business logic — Law #3)
│   └── [slug].astro
├── components/           # Module-private UI components
└── actions.ts            # Server actions / mutations
// modules/blog/index.module.js
export default {
  id: "blog",
  name: "Blog",
  routes: [
    { path: "/blog", entrypoint: "./routes/index.astro" },
    { path: "/blog/[slug]", entrypoint: "./routes/[slug].astro" },
  ],
  hooks: {
    "launcher:action": ["./actions/commands.js"],
  },
};

Law #4 (Inviolable): A feature module (modules/blog/) may only import from modules/core/ or @stnd/* packages. Sibling feature modules must never import each other directly — coordinate through Hooks.


Module Roles: Features vs Foundation Spine

Standard modules fall into two structural roles declared in their manifest:

// modules/core/index.module.js
export default {
  id: "core",
  role: "foundation", // Declares this module as the shared foundation spine
  name: "Application Spine",
  description: "Domain models, session context, and root application shell."
};
  1. Feature Modules (role: "feature", default): Self-contained vertical slices implementing a single user capability (e.g., modules/writer/, modules/culling/). They encapsulate their routes, actions, and UI views. Sibling feature modules never import each other directly.
  2. Foundation Spine (role: "foundation", convention: modules/core/): The shared kernel of the application. It holds domain models (models/), root shell layouts, authentication/session context, and base provider contracts. It can be imported by any feature module, but it must never import from a feature module.

Domain Models & The Provider Pattern

Core application entities that multiple features manipulate (such as Note in Garden, or Asset and Library in Reveal) must be authored as strongly typed domain models in modules/core/models/, never buried inside a specific feature slice.

When an application supports multiple backends or storage drivers (such as photo libraries backed by Immich, Apple Photos, or the local filesystem):


Add a route

routes: [
  { path: "/blog", entrypoint: "./routes/index.astro" },
  { path: "/blog/[slug]", entrypoint: "./routes/post.astro" },
],

Add global styles, local themes, or private fonts

Because @stnd/core discovers every *.module.js file in your project’s ./modules/ folder, external applications (npm install @stnd/core) can register custom themes, licensed commercial fonts, and UI component libraries locally without touching the framework’s core packages:

// modules/custom-brand/index.module.js
export default {
  id: "custom-brand",
  styles: [
    "./fonts/licensed-typeface.css", // private font kept in your repo
    "./styles/brand-theme.scss",     // custom [data-theme="brand"] tokens
  ],
  scripts: ["./client.js"],
};

Contribute to the site’s nav, title, or any other config

Modules deep-merge into the global config via the config key:

// modules/seo/index.module.js
export default {
  id: "seo",
  config: {
    nav: {
      footer: [{ title: "Privacy", url: "/privacy" }],
    },
  },
};

Arrays (like nav.header) are concatenated across modules — each
module appends its items. Objects are recursed. Scalars are
protected: two modules claiming the same scalar key is a build error.

Config Conflict: Key "title" was claimed by both "core" and "seo".
Only one module may define a scalar config value.
Use arrays or nested objects for multi-module contributions.

Your top-level astro.config.mjs options always win last, silently —
they’re the final override. The merged result is available everywhere via
virtual:stnd/config:

import config from "virtual:stnd/config";
console.log(config.nav.header); // all modules' nav items, combined

Declare a dependency

export default {
  id: "shop",
  dependencies: ["stnd-styles", "core", "@stnd/fonts/kalice"],
  // ...
};

The loader guarantees a dependency is ready before your module runs — a
topological sort (Kahn’s algorithm) does the ordering, so you never have
to hand-tune load order yourself. Unresolved dependencies log a warning
but don’t crash; circular dependencies throw immediately.

Provide a value to the runtime store

For state other modules or components need without importing you
directly (a simple Map-based provide/inject):

// in the module manifest
store: {
  user:   "./models/Visitor.js#visitorStore",  // named export
  search: "./search.js",                        // default export
}
// in any component
import { inject } from "@stnd/store";
const user = inject("user");

Values are initialized before any component mounts.

Disable a module without deleting it

export default {
  id: "analytics",
  status: "disabled", // loaded but not processed
  // ...
};

Or exclude a gold standard module entirely from your Astro config:

standard({
  moduleExclude: ["@stnd/launcher"],
});

If you need to know the load order

  1. Gold standard modules — internal system modules, in their declared order
  2. moduleLoad entries — your explicit additions, in the order you wrote them
  3. Discovered modules — auto-found in modules/, alphabetical
  4. Dependencies — pulled in before the module that requires them

Explicit modules (moduleLoad) always load before auto-discovered ones.
Within a tier, alphabetical order is the stable tiebreaker.

Quick reference — every manifest key

Key Type Description
id string Required. Unique identifier. Duplicate IDs throw.
name string Display name for logs and dev tools.
description string Short description.
status "enabled" | "disabled" Skip processing when "disabled".
dependencies string[] Module IDs that must load first.
config object Merged into global config. Scalar conflicts throw.
routes { path, entrypoint }[] Astro routes to inject.
styles string[] CSS/SCSS files, injected on every page.
scripts string[] JS files or CDN URLs, injected on every page.
middleware string[] | { entrypoint, order }[] Request handlers. order controls sequence.
actions string Path to Astro Actions file.
hooks { [hookName]: entry[] } UI zones and lifecycle hooks — see Hooks & Extension Points.
store { [key]: "path#export" } Runtime provide/inject registrations.
aliases { [alias]: path } Vite path aliases.
content string Path to content collections definition.