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() returns null and 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

HelperModuleReturns / does
products:getAll(filters?)productsProducts; filters: category, status, limit, offset; each with listing_image (the 640px image for cards)
products:getFeatured(limit = 4)productsPublished featured products
products:getOne(id), products:getBySlug(slug)productsOne product, or null
pages:render(slug)pagesA page's HTML (powers {{ page='slug' }})
pages:getNavItems()pagesMenu entries for pages marked "Show in navigation"
pages:homeSections()pagesPublished pages shown as sections of the home page, in menu order (powers {{#each homeSections}})
pages:contentForUsageScan()pagesEvery page's title, status and content, for the "Used in" scan (src/core/usage.ts)
widgets:render(type, name, overrides?)widgetsA widget instance's HTML (powers widget shortcodes)
widgets:getTypeAssets(type)widgetsThe type's CSS/JS URLs
widgets:listInstances(), widgets:ensureInstance(type, name, params?)widgetsThe 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)statsAnalytics data
stats:dashboardSummary(siteName)statsTraffic numbers for Admin > Dashboard
email:send({ to, subject, html, text?, replyTo? })emailSends through the configured provider; returns { success, error? }
email:registerProvider(name, sendFn), email:getProviders(), email:getProvider(), email:getConfig(), email:isConfigured()emailPluggable email providers
media:sync()mediaRe-scans uploads/ into the Media Manager
media:listingUrl(url), media:thumbnailUrl(url)mediaFor an /uploads/... image: its 640px-wide listing image (cards) or its 320px square thumbnail (admin grids); any other address comes back unchanged
collections:embedList()collectionsThe 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

  1. Put the functions in an object in your module's init.ts.
  2. Register them with the {moduleId}:{name} prefix:
    Object.entries(blogHelpers).forEach(([name, fn]) => registerHelper(`blog:${name}`, fn));
  3. Call them anywhere with callHelper<Post[]>('blog:getRecent', 3), giving the result type you expect (without it the result is unknown).

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.