Overview
The helper registry (modules/registry.ts) is a named list of functions. A module registers functions under names like products:getFeatured; any other module, site init.ts or the core calls them by name with callHelper().
Why not just import? A direct import ties two modules together: if one is removed or disabled, the other breaks, and two modules importing each other create circular dependencies. Calling by name keeps modules independent: when a helper is missing,callHelper()returnsnulland the caller falls back.
Core API
registerHelper(name, fn)
import { registerHelper } from '../registry.js';
registerHelper('blog:getRecent', async (limit = 5) =>
dbAll("SELECT * FROM articles WHERE status = 'published' ORDER BY created_at DESC LIMIT ?", [limit])
);
Registering the same name again replaces the earlier function.
callHelper<T>(name, ...args)
import { callHelper } from '../registry.js'; // from modules/<name>/init.ts
// from modules/site/<name>/init.ts use '../../registry.js'
const recent = (await callHelper<Post[]>('blog:getRecent', 3)) ?? [];
Returns whatever the helper returns, or null (and logs a warning) when no helper has that name. Helpers are found by name at run time, so TypeScript cannot know what one returns: give the type you expect (callHelper<Post[]>); without it the result is unknown.
getAllHelpers()
Returns every registered helper by name; useful for debugging.
Helpers Available Today
| Helper | Module | Returns / does |
|---|---|---|
products:getAll(filters?) | products | Products; filters: category, status, limit, offset; each with listing_image (the 640px image for cards) |
products:getFeatured(limit = 4) | products | Published featured products |
products:getOne(id), products:getBySlug(slug) | products | One product, or null |
pages:render(slug) | pages | A page's HTML (powers {{ page='slug' }}) |
pages:getNavItems() | pages | Menu entries for pages marked "Show in navigation" |
pages:homeSections() | pages | Published pages shown as sections of the home page, in menu order (powers {{#each homeSections}}) |
pages:contentForUsageScan() | pages | Every page's title, status and content, for the "Used in" scan (src/core/usage.ts) |
widgets:render(type, name, overrides?) | widgets | A widget instance's HTML (powers widget shortcodes) |
widgets:getTypeAssets(type) | widgets | The type's CSS/JS URLs |
widgets:listInstances(), widgets:ensureInstance(type, name, params?) | widgets | The instances (for the editor's Widget button); create an instance if it does not exist yet (seeding) |
stats:getPageViews(days), stats:getTopPages(days, limit), stats:getDeviceStats(days) | stats | Analytics data |
stats:dashboardSummary(siteName) | stats | Traffic numbers for Admin > Dashboard |
email:send({ to, subject, html, text?, replyTo? }) | Sends through the configured provider; returns { success, error? } | |
email:registerProvider(name, sendFn), email:getProviders(), email:getProvider(), email:getConfig(), email:isConfigured() | Pluggable email providers | |
media:sync() | media | Re-scans uploads/ into the Media Manager |
media:listingUrl(url), media:thumbnailUrl(url) | media | For an /uploads/... image: its 640px-wide listing image (cards) or its 320px square thumbnail (admin grids); any other address comes back unchanged |
collections:embedList() | collections | The collections for the editor's Collection button |
The core uses the registry too: the renderer calls widgets:render and pages:render for shortcodes and pages:getNavItems for the menu, the shared contact form calls email:send, and registration and password reset use email:isConfigured and email:send.
Example: Featured Products on a Site's Home Page
The products module registers its helpers; a site's init.ts calls one and hands the result to the theme's home.html.
In modules/products/init.ts: registering
const productsHelpers = {
getFeatured: async (limit = 4) => {
const rows = await dbAll(
"SELECT * FROM products WHERE status = 'published' AND featured = 1 ORDER BY created_at DESC LIMIT ?",
[limit]
);
return rows.map((p) => ({ ...p, formattedPrice: `$${Number(p.price).toFixed(2)}` }));
},
// getAll, getOne, getBySlug ...
};
Object.entries(productsHelpers).forEach(([name, fn]) => registerHelper(`products:${name}`, fn));
In modules/site/acme/init.ts: calling
import type { AppModule } from '../../../src/core/types.js';
import { callHelper } from '../../registry.js';
export const acmeSite: AppModule = {
id: 'acme',
name: 'Acme',
version: '1.0.0',
description: 'Acme site',
isSite: true,
site: {
routes: [
{
path: '/',
cacheTtl: 60,
cacheTags: ['products'], // cleared when products change
// Plain data: rendered with themes/<theme>/home.html
handler: async () => ({ featured: (await callHelper<Array<Record<string, unknown>>>('products:getFeatured', 3)) ?? [] }),
},
],
},
};
In themes/acme/home.html: displaying
{{#each featured}}
<a href="/products/{{ slug }}">{{ title }} — {{ formattedPrice }}</a>
{{/each}}
If the products module is removed, the helper is missing, featured is an empty list, and the page still renders.
Adding Your Own Helpers
- Put the functions in an object in your module's
init.ts. - Register them with the
{moduleId}:{name}prefix:Object.entries(blogHelpers).forEach(([name, fn]) => registerHelper(`blog:${name}`, fn)); - Call them anywhere with
callHelper<Post[]>('blog:getRecent', 3), giving the result type you expect (without it the result isunknown).
Where to register: at the bottom of init.ts (runs once, when the file is loaded at startup), or inside the module's onInit hook if the helper needs the module to be initialized first.
Best Practices
- Always prefix names with your module id to avoid collisions.
- Always handle
null:(await callHelper<Item[]>('x:y')) ?? []. - Return display-ready data (formatted prices, booleans like
isFeatured) so callers don't need to know your table layout. - Keep helpers small: one query or one action each.
- Disabled modules keep their helpers registered; check the module state yourself if a disabled module's data must not appear. (The renderer does this for widget and page shortcodes: they render nothing while their module is off.)
Under the Hood
type Helper = (...args: never[]) => Promise<unknown>;
const helpers = new Map<string, Helper>();
export function registerHelper(name: string, fn: Helper) { helpers.set(name, fn); }
export async function callHelper<T = unknown>(name: string, ...args: unknown[]): Promise<T | null> {
const fn = helpers.get(name);
if (!fn) { logger.warn(`Helper not found: ${name}`); return null; }
return (await fn(...args)) as T;
}
Modules are loaded one after another before the server starts accepting requests, so every helper registered while loading is available to the first request.