Guide
Worker modules: the module manifest
Every worker template that ssg new worker scaffolds describes itself in a
file at its root, module.json: what it is called, where its admin panel lives,
which navigation entries it offers, which permissions its admin surface
distinguishes, which endpoints describe it, and how to really switch it off.
A worker with such a file is a module.
The manifest is a description only. It never holds a secret, a configuration value or data — anyone allowed to see the module's admin endpoints may see it.
- Format:
workers/module.schema.json(JSON Schema, draft 2020-12) — the one definition of the format. - Reader:
workers/module-manifest.ts— a dependency-free TypeScript validator that interprets that schema and adds the checks a schema cannot express. - Summary format:
workers/module-summary.schema.json— what a module's summary endpoint answers; the same reader checks it (readSummary).
What reads the manifest today
| Reader (1.9.9) | What it does with it |
|---|---|
| The module itself | GET …/api/module in comments, newsletter, newsletter-ui, auth, core, ecommerce (/api/shop/module), editor-ui and designer-ui serves it, behind each module's own admin check |
| The site build | Checks the manifests of the workers in workers: and of modules: entries and writes them into a module registry — only when one of the workers is core |
The core worker |
Reads that registry, asks each module for its manifest, status and summary, and serves the admin home page (/core/) and the shared navigation (/core/nav.js), which the comments, newsletter-ui, auth, ecommerce, editor-ui and designer-ui panels include — see workers/core/README.md |
The auth worker |
Builds roles from the declared permission names (its own manifest plus the ones you list in AUTH_KNOWN_PERMISSIONS; node workers/auth/scripts/auth-permissions.mjs workers/*/module.json prints that list) and puts each account's effective permissions in the perms of its access token |
Every module in auth mode |
Checks the token's perms against the permission each action needs: comments, newsletter, newsletter-ui, core, ecommerce and auth itself for people, web-push, republish-trigger and a few reads of ecommerce (export, sales figures, its summary) for service tokens; editor-ui and designer-ui for both, on every REST route and MCP tool |
workers/modules.test.ts |
Checks every bundled template's manifest against its code, and each summary against the summary format |
A module enforces permissions only in the auth mode. With a shared password
or Cloudflare Access whoever passes the module's check may do everything, as
before; that is a supported choice for one person, not a gap
(which mode to choose).
Fields
1{
2 "id": "comments",
3 "contract": 1,
4 "version": "1.0.0",
5 "kind": "pages-function",
6 "title": { "en": "Comments", "pl": "Komentarze", "hi": "टिप्पणियाँ", "de": "Kommentare", "fr": "Commentaires" },
7 "description": { "en": "Reader comments stored in D1, …", "pl": "…", "hi": "…", "de": "…", "fr": "…" },
8 "panel": "/comments-admin.html",
9 "nav": [
10 {
11 "label": { "en": "Moderation queue", "pl": "Kolejka moderacji", "hi": "मॉडरेशन कतार", "de": "Moderationswarteschlange", "fr": "File de modération" },
12 "path": "/comments-admin.html",
13 "permission": "comments:read"
14 }
15 ],
16 "permissions": [
17 { "name": "comments:read", "description": { "en": "View the comments in the moderation queue: …", "pl": "…", "hi": "…", "de": "…", "fr": "…" } },
18 { "name": "comments:moderate", "description": { "en": "Approve a comment or mark it as spam.", "…": "…" } },
19 { "name": "comments:delete", "description": { "en": "Delete a comment for good, and run the purge …", "…": "…" } },
20 { "name": "comments:import", "description": { "en": "Import comments in bulk from another system, …", "…": "…" } }
21 ],
22 "endpoints": { "manifest": "/api/comments/module", "summary": "/api/comments/module/summary" },
23 "disable": { "en": "Remove workers/comments from the workers: list in .ssg.yaml, …", "pl": "…", "hi": "…", "de": "…", "fr": "…" }
24}
| Field | Type | Meaning |
|---|---|---|
id |
string, ^[a-z][a-z0-9-]*$ |
The template's directory name (workers/<id>). |
contract |
integer ≥ 1 | Version of this manifest format. Currently 1. |
version |
MAJOR.MINOR.PATCH |
The module's own version, independent of the ssg release. Bump it when the module's routes, panel or permissions change. |
kind |
pages-function | worker |
pages-function: merged into the site's Pages build through workers:. worker: a standalone Worker with its own wrangler.toml (e.g. newsletter-ui). |
title, description |
text | Name and one-sentence description. |
panel |
path or null |
The module's admin panel; null when it has none. |
nav |
array (≤ 12) | Entries a shared navigation may show: label (text), path, permission (a name from permissions). Empty when there is no panel. |
permissions |
array (≤ 32) | Every permission the admin surface distinguishes: name (namespace:action), description (text) and, optionally, sensitive: true — auth then treats the permission as sensitive besides its name rules: a service token carries it only with an owner's allowance (service tokens). |
endpoints |
object of paths | Endpoints that describe the module. Known keys: manifest (this file), health, summary (the summary endpoint), openapi. Only endpoints the module really serves are listed. |
disable |
text | How to really switch the module off. Hiding a module in a navigation does not disable it; this says what does (remove it from workers: and deploy, delete the Worker, revoke a webhook…). |
Text is an object with a non-empty string for each of the five panel
languages — en, pl, hi, de, fr — at most 600 characters each. More
language codes may be added.
Paths are relative to the module's base. For a pages-function module the
base is the site root, so /comments-admin.html is literally that URL. For a
worker module the base is wherever the Worker is mounted
(NEWSLETTER_UI_BASE, default /newsletter-admin), so newsletter-ui's panel
/ is /newsletter-admin/. A path starts with /, has no empty, . or ..
segment, no query, and no scheme or host — a manifest can never point a
navigation to another site. panel and nav paths may end in a #fragment
for panels with hash routing (/#/campaigns); endpoint paths may not.
Permission names are namespace:action, lowercase. The namespace is the
module's own id, or the id of the module whose data it acts on: newsletter-ui
declares newsletter:* permissions because it works on the newsletter
template's subscribers, and a permission declared by both means the same in
both (same description — the test checks). Wildcards (newsletter:*, *)
belong to role definitions in auth, never to a declaration.
Permissions of the bundled templates
| Template | Permissions | Derived from |
|---|---|---|
comments |
comments:read, comments:moderate, comments:delete, comments:import |
GET /api/comments/admin (read); approve/spam (moderate); delete and purge (delete); POST /api/comments/import (import) |
newsletter |
newsletter:read, newsletter:export, newsletter:settings |
GET /api/newsletter/admin counts (read); ?format=csv (export); purge (settings) |
newsletter-ui |
newsletter:read, newsletter:edit, newsletter:send, newsletter:import, newsletter:export, newsletter:erase, newsletter:suppress, newsletter:settings |
One per level of trust of its admin API: viewing, editing drafts and subscriber fields, mailing real people, importing, exporting, erasing a person, managing suppressions, maintenance |
auth |
auth:admin, auth:invite |
Managing people, roles, groups, grants and anyone's sessions (admin); inviting people with roles no wider than one's own (invite) |
ecommerce |
ecommerce:read, ecommerce:orders, ecommerce:refund, ecommerce:products, ecommerce:settings, ecommerce:export |
One per level of trust of the shop's admin API, route by route (functions/api/shop/_permissions.ts): viewing, handling orders, refunds (money leaves the shop), products and VAT rates, settings and payment providers, exports with buyers' personal data. A service token is accepted only on GET export, stats, manifest and summary, naming the permission exactly (the shop's README) |
core |
core:manage |
Module management: order, visibility, labels and notes |
editor-ui |
editor-ui:read, editor-ui:publish (sensitive), editor-ui:media, editor-ui:delete |
Reading content, history and the media library; publishing articles (sensitive: ssg renders raw HTML in Markdown, so a publisher can put scripts on the site's pages); adding images; deleting. Each REST route and MCP tool checks its own (EDITOR) |
designer-ui |
designer-ui:read, designer-ui:settings, designer-ui:advanced (sensitive), designer-ui:theme (sensitive) |
Reading settings and theme; publishing plain settings; settings that run code, deploy, read files or refer to $NAME (advanced); theme files, which are code the build runs (theme) (DESIGNER) |
web-push |
web-push:notify |
POST /api/push/notify (the shared key PUSH_KEY, or a service token holding it) |
republish-trigger |
republish-trigger:run |
POST /api/republish (the shared key REPUBLISH_KEY, or a service token holding it) |
contact-form, conversions-proxy, cookie-consent, dynamic-price, rate-limit, stripe-checkout |
none | Public endpoints, or ones authenticated by a provider's signature (Stripe), not by a person or a key you hand out |
The two machine-called templates declare their one action so that an auth
service token can be granted exactly that; the shared keys keep working.
The three permissions marked sensitive are declared "sensitive": true in
their module.json. auth also knows them as sensitive on its own
(_bundled-sensitive.ts), so a service token carries them only with an
owner's allowSensitive even when AUTH_KNOWN_PERMISSIONS lists them as bare
names or leaves the module out.
Versioning
- A reader ignores fields it does not know. Adding an optional field never needs a new contract.
- A reader refuses a manifest whose
contractis newer than the newest it understands, with a message that names the module and says to upgrade (module "x" uses manifest contract 2, but this reader understands contract 1 at most — upgrade ssg (and the core worker) to read it). The contract number changes only when an existing field changes meaning or a new field becomes required. - A module's
versionis its own business; readers display it, they do not compare it.
The manifest endpoint
| Template | Route | Auth |
|---|---|---|
comments |
GET /api/comments/module |
same gate as /api/comments/admin (Cloudflare Access or COMMENTS_ADMIN_PASSWORD) |
newsletter |
GET /api/newsletter/module |
same gate as /api/newsletter/admin |
newsletter-ui |
GET {base}/api/module |
the worker's admin auth, like every /api/ route |
editor-ui, designer-ui |
GET {base}/api/module |
an auth access token holding editor-ui:read / designer-ui:read |
auth |
GET /api/auth/module |
an access token holding auth:admin |
core |
GET /api/core/module |
core's own sign-in, like every /api/core/ route |
ecommerce |
GET /api/shop/module |
the admin API's gate (Access, auth with ecommerce:read, or SHOP_ADMIN_PASSWORD) |
The answer is the manifest as JSON (cache-control: no-store); a refusal is
byte for byte what the module's admin endpoint answers. It needs no database.
The other templates have no authenticated admin surface to put it behind, so
they ship the file only: serving it publicly would make every site announce
which workers it runs, and the module registry reads
the file at build time.
A Pages Function cannot read files at runtime, and the site build copies only a
template's functions/ tree, so a Pages template imports a generated copy of
its manifest — functions/api/<name>/_module.ts (the leading underscore keeps
it out of the route table). workers/modules.test.ts fails while a copy
differs from module.json; UPDATE_MODULE_TWINS=1 node --test 'workers/*.test.ts'
rewrites the copies. A standalone Worker imports module.json directly
(import manifest from "../module.json" with { type: "json" }); wrangler
bundles it at deploy time.
The summary endpoint
An admin home page needs the same three things from every module, in one
shape: a few numbers, what needs a person, and what is wrong with the
configuration. A module that can answer that declares
endpoints.summary and serves it with GET.
1{
2 "contract": 1,
3 "generatedAt": "2026-11-13T10:00:00.000Z",
4 "metrics": [
5 { "key": "pending", "label": { "en": "Awaiting moderation", "pl": "Czekają na moderację", "…": "…" }, "value": 12 }
6 ],
7 "attention": [
8 { "severity": "action", "text": { "en": "12 comments await moderation.", "pl": "12 komentarzy czeka na moderację.", "…": "…" }, "href": "/comments-admin.html" },
9 { "severity": "warning", "text": { "en": "The oldest comment in the queue has been waiting for 9 days.", "…": "…" }, "href": "/comments-admin.html" }
10 ],
11 "problems": [
12 { "code": "no_turnstile_secret", "text": { "en": "Neither COMMENTS_TURNSTILE_SECRET nor TURNSTILE_SECRET is set: every new comment is refused.", "…": "…" } }
13 ],
14 "series": { "label": { "en": "Sign-ups", "…": "…" }, "points": [{ "day": "2026-11-13", "value": 4 }] }
15}
| Field | Rule |
|---|---|
contract |
Version of the summary format, currently 1 (independent of the manifest's). A reader refuses a newer one, like a manifest. |
generatedAt |
ISO 8601 in UTC, when the module computed the answer. |
metrics |
At most 4: key (camelCase, ^[a-z][A-Za-z0-9]*$), label (text), value (a number ≥ 0), optional unit (percent or days; absent for a count). Two modules that read the same data use the same key, label and value for the same number. |
attention |
At most 10, most serious first: severity, text (a whole sentence), href. |
problems |
At most 10: code (snake_case) and text. Names what is missing or unusable, never a secret's value. |
series |
Optional, one daily series for a small chart: label and at most 90 points {day: "YYYY-MM-DD", value}, oldest first, each day once. |
Severity. action: waits for a person's decision or work (comments to
moderate, a campaign the send engine paused, uncertain sends).
warning: something is going wrong or degrading (a stale queue, jobs that
ran out of retries). info: good to know, nothing to do.
Links. href is a path inside the module's own panel, relative to the
module's base, with the same grammar as a manifest nav path — an optional
#fragment for hash routing (/#/campaigns?status=paused), never a scheme,
host, //, .. or query. A home page joins it to the module's base; a
summary can never send a person to another site. A module without a panel has
no attention items.
Text. Every text is a text in the five panel languages, at most
400 characters each, and a reader renders it as plain text — never as
HTML. Counts are written into the sentence in each language's plural form
(Intl.PluralRules) and number format.
Size. Besides the caps above, a whole answer is at most 32 KiB of UTF-8
JSON (SUMMARY_MAX_BYTES). Readers ignore fields they do not know.
Aggregates only. A summary holds counts and fixed sentences. No address,
name, comment text, campaign subject, token, IP, user agent or any other
per-person value — each template's tests seed recognisable personal data and
scan the serialized summary for it (and for any @).
Auth. The summary is behind the same gate as the module's manifest and
admin API, and every refusal is byte for byte what the admin endpoint answers.
In the auth mode it needs the module's read permission (comments:read,
newsletter:read, auth:admin, ecommerce:read); with the password or Cloudflare Access
whoever passes may read it.
Which templates serve one
| Template | Route | Metrics | Attention | Problems | D1 statements |
|---|---|---|---|---|---|
comments |
GET /api/comments/module/summary |
pending, approved, spam |
action while comments await moderation; also warning once the oldest has waited 7 days (STALE_DAYS); both link to /comments-admin.html |
no_database, no_turnstile_secret, access_incomplete (only one of COMMENTS_ACCESS_TEAM / _AUD set) |
1 |
newsletter |
GET /api/newsletter/module/summary |
confirmed, pending, unsubscribed |
none (no panel) | no_database, no_turnstile_secret, mail_unusable (double opt-in configured but the transport can never send — sign-ups are refused), access_incomplete |
1 |
auth |
GET /api/auth/module/summary |
accounts, pendingInvitations, liveSessions, missingFactor |
action: accounts without a second factor their roles need; warning: a signing key past the yearly rotation advice; info: open invitations — all linking into /auth/admin/ |
mail_broken, mfa_key_short, mfa_roles_invalid, access_misconfigured |
a few, aggregates only |
ecommerce |
GET /api/shop/module/summary |
paidOrders, revenue (after refunds, last 30 days, base currency in its main unit — the currency is in the label, the format has no currency unit), refunds, productsOnSale |
action: orders needing review, paid orders without download links (/ecommerce-admin/#orders); warning: failed payment notifications in 7 days and Stripe test keys or the PayPal sandbox on a public host (#payments), outgoing messages failing 5 times (#log), VAT rates ending within 30 days with no successor (#vat); info: VAT table unchanged for a year |
no_database (Access and auth only; the password mode needs D1 for its lockout and answers 503), no_files, no_kv, no_gateway, no_mail, no_seller_details |
2 (plus the cached settings read) |
newsletter-ui |
GET {base}/api/module/summary |
confirmed, pending, campaignsInProgress, suppressed |
action: campaigns paused by the send engine (/#/campaigns?status=paused), uncertain sends (/#/), pending subscribers never sent a confirmation (/#/subscribers?status=pending); warning: dead-lettered jobs (/#/) |
no_subscribers_table, no_transport, transport_unusable, no_site_url, no_sender, no_queue — the dashboard's own warnings, in its own words |
≤ 3 |
editor-ui |
GET {base}/api/module/summary |
daysSinceContentChange, contentFolders |
info: the branch publications go to |
repo_not_configured, repo_token_rejected, repo_not_found, repo_unreachable, site_config_unreadable, site_config_overridden, site_config_partial, no_content_dirs, bad_override |
none (it asks GitHub, no database) |
designer-ui |
GET {base}/api/module/summary |
overlaySettings (keys set in the panel), themeFiles |
info: the branch publications go to |
repo_not_configured, repo_token_rejected, repo_not_found, repo_unreachable, config_unreadable, config_partly_read, overlay_invalid, theme_not_editable |
none (it asks GitHub, no database) |
newsletter-ui's series is the sign-ups per day of the last 30 days. Without
the subscribers table it still answers: the campaign and suppression numbers
and the problem no_subscribers_table.
newsletter and newsletter-ui together. Both read the same
subscribers table, and both report confirmed and pending under the same
keys, with the same labels and the same values — workers/modules.test.ts
runs both on one database. When a site has both, a home page should show
newsletter-ui's summary and may hide newsletter's: it is a superset
(campaigns, suppressions, the series) and has a panel to link to.
newsletter's summary is for a site that runs the sign-up form without the
panel.
No summary: no gate. The other templates have no authenticated admin
surface, and an unauthenticated summary would tell anyone which bindings and
secrets a site lacks — reconnaissance for an attacker. web-push and
republish-trigger have only a machine key (PUSH_KEY, REPUBLISH_KEY) held
by CI; a home page forwards the person's credential, never such a key, and
handing the key to people would also let them trigger notifications or
rebuilds. auth can now authenticate a person for them, but they have no
person-facing admin check yet, so their summaries are still to come:
| Template | What its summary would say, once it has a gate |
|---|---|
web-push |
subscriptions, time of the last notification (needs recording), missing VAPID keys or PUSH_KEY |
republish-trigger |
missing hook or key |
cookie-consent |
consents by category over recent days, when the log is on |
contact-form, conversions-proxy, dynamic-price, rate-limit, stripe-checkout |
configuration state only: which required secrets and bindings are set |
What a summary costs on D1
Each summary is a fixed, small number of statements (the table above; the
first request of an isolate adds the template's schema check, and
newsletter-ui's password mode reads one lockout row per request). That is
far inside the 50 queries per Worker invocation of the Workers Free plan
(1 000 on Paid).
The budget that matters is rows read: D1 counts every row a statement scans, and a count over a table scans it (an index makes the scan cheaper, not shorter). The Free plan includes 5 million rows read per day. Roughly, per summary:
| Template | Rows read |
|---|---|
comments |
every comment (one pass over the status index) |
newsletter |
every subscriber |
ecommerce |
every order (twice), every refund and product, the unsent outbox rows, a week of payment notifications, the VAT table |
newsletter-ui |
every subscriber twice (status counts, sign-up series), the pending ones again, every campaign_sends row, the suppressions |
So with 100 000 subscribers one newsletter-ui summary reads a few hundred
thousand rows — about 20 summaries a day on the Free plan, besides everything
else the site reads. A home page therefore asks for summaries when it is
opened or refreshed by hand, never on a timer, and a large list
belongs on Workers Paid.
Adding a summary to your module
- Copy
workers/module-summary-kit.tsinto your worker unchanged (a Pages Function: asfunctions/…/_summary-kit.ts). It holds the types, the caps,counted(phrase, n)(a sentence with a count in five languages) andsummaryOf(parts)(sorts attention by severity, applies the caps, stampsgeneratedAt). - Compute the numbers with one or two aggregate statements (
COUNT,GROUP BY) — never by reading rows into the worker. - Serve it behind your admin check and declare
endpoints.summary. - In the ssg repository, keep a
test/summary-sample.tsin the template: run with the template'stest/resolve.mjs, it drives the handler through the template's test fakes and prints the body.workers/modules.test.tsvalidates it withreadSummaryand checks everyhrefagainst the panel's files; a template that declares a summary without serving it fails there.workers/module-summary.test.tsfails while a copy of the kit differs from the original.
The module registry
The build knows the site's whole worker list; the registry hands that
knowledge to the core worker. It is written only when a worker in
workers: (or worker:) has a module.json with "id": "core". Without such
a worker the build writes nothing new and its output is byte for byte what
it was before — the golden corpora pin that.
With core, the build reads the module.json of every worker it bundles and
of every modules: entry that has a dir, checks each with the Go reader
(internal/modules, the same rules and messages as module-manifest.ts), and
writes functions/_ssg-modules.json in the output. A worker without a
module.json is not a module and is simply not listed.
Modules the build cannot see — a standalone Worker deployed on its own — are declared in the site configuration:
1modules:
2 - id: newsletter-ui
3 url: /newsletter-admin # the module's base path on the same host
4 dir: workers/newsletter-ui # optional: read title/nav/permissions at build time
url is a path on the site's own host; a scheme, a host, //, .., a
backslash, a query or a fragment is a configuration error naming the file and
the key. Without dir the registry records the id and the base, and core
asks the module for its manifest at runtime.
Where it is, and who can read it
A Pages Function cannot read static files, so the registry lives inside the Functions tree and the core function imports it:
1import registry from "../../_ssg-modules.json" with { type: "json" };
wrangler bundles it into the function at deploy time. The leading underscore
keeps it out of the route table, and wrangler pages deploy never uploads the
functions/ directory as static assets, so the file is not publicly served
(checked with wrangler pages functions build: the import bundles and no
route is generated for the file). A worker that ships a file of the same name
is refused. Like the rest of functions/, a deploy target other than
Cloudflare Pages uploads it as an ordinary file.
Shape
1{
2 "format": 1,
3 "modules": [
4 {
5 "id": "comments",
6 "kind": "pages-function",
7 "base": "/",
8 "bundled": true,
9 "contract": 1,
10 "version": "1.0.0",
11 "manifest": { "contract": 1, "id": "comments", "…": "the whole module.json" }
12 },
13 {
14 "id": "shop",
15 "kind": null,
16 "base": "/shop",
17 "bundled": false,
18 "contract": null,
19 "version": null,
20 "manifest": null
21 }
22 ],
23 "available": [
24 { "id": "contact-form", "kind": "pages-function", "title": "Contact form" }
25 ],
26 "theme": null
27}
| Field | Meaning |
|---|---|
format |
Version of this document. A reader refuses a newer one. |
modules |
Sorted by id. base is / for a Pages Function in this build and the configured url otherwise; bundled says which. kind, contract, version and manifest are null when the build has no manifest for the module (no dir, or a dir whose manifest is unusable). manifest is the full module.json, unknown fields included, keys sorted. |
available |
Templates this ssg binary ships that the site does not use: id, kind, English title, sorted by id. |
theme |
The panels' look computed from admin_theme:, or null when the site sets none — see below. |
No timestamps and no paths of the machine that built it: the same site gives the same bytes.
The panels' look (theme)
With admin_theme: in .ssg.yaml (ADMIN-THEME)
the build validates it, derives the palette (internal/admintheme) and
writes the result here — and the colours and fonts again as /core/theme.css,
which the build writes over the empty file the core template ships. The
worker serves both as they are; it does no colour maths.
1"theme": {
2 "name": "Anna's Kitchen",
3 "logo": "/img/logo.svg", "logoDark": null,
4 "fontDisplay": "\"Georgia\", \"Noto Serif\", \"Noto Serif Devanagari\", \"Nirmala UI\", serif",
5 "fontUi": null,
6 "fontFiles": [{ "family": "Brand Sans", "src": "/fonts/brand-sans.woff2", "format": "woff2", "weight": "400 700", "style": "normal" }],
7 "main": "#1b3a4b", "accent": "#e07a5f", "derived": [],
8 "light": { "primary": "#1b3a4b", "on-primary": "#ffffff", "…": "every themed token" },
9 "dark": { "primary": "#698a9d", "…": "every themed token" },
10 "adjustments": [
11 { "scheme": "dark", "token": "primary", "requested": "#1b3a4b", "used": "#698a9d", "reason": "contrast", "against": "surface" }
12 ],
13 "checks": [{ "scheme": "light", "fg": "primary", "bg": "surface", "ratio": 11.97, "minimum": 4.5 }]
14}
| Field | Meaning |
|---|---|
name, logo, logoDark |
The brand for the shared navigation (/api/core/modules → brand); null when unset. Logos are paths on the site's own host. |
fontDisplay, fontUi |
The font stacks as written to theme.css (--font-display, --font-ui), fallbacks included; null when unset. |
fontFiles |
The @font-face blocks in theme.css. |
main, accent, derived |
The two brand colours (lowercase #rrggbb); derived lists the one the build made from the other. null when no colour is set. |
light, dark |
Token name (without --) → colour, per scheme: primary, on-primary, primary-soft, on-primary-soft, focus, c1–c5, nav-bg, on-nav, nav-muted, nav-hover, nav-control, nav-current — exactly the names workers/core/public/core/tokens.css defines. Empty when no colour is set. |
adjustments |
Each brand colour that could not serve a role as given: scheme (light, dark, or both for the bar), token, requested, used, reason (contrast or distinct) and the token it was measured against. |
checks |
Every contrast pair the panels use that involves a themed token: ratio rounded down to two decimals, minimum 4.5 (text) or 3 (marks, edges, focus). |
The worker reads the field defensively (functions/api/core/_theme.ts): a
value outside the shape above becomes null or is left out. /core/theme.css
sets the light tokens on :root, the dark ones under @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) } and under
:root[data-theme="dark"] — the selectors of tokens.css — so a panel loads
it after its own tokens and each rule wins by order. check_admin_theme
(off, warn default, strict) reports a logo or font file missing from the
output, a tokens: override that breaks a pair, and admin_theme without a
core worker.
Checks (check_modules)
check_modules: off | warn | strict — warn by default, because findings
only exist on a site that uses modules, and there a module silently missing
from the navigation is what to avoid. strict (or a --strict build) fails
on any finding. Each names the file and the key:
| Finding | Effect on the registry |
|---|---|
A bundled worker's module.json fails the schema, has a newer contract or is unreadable (workers/x/module.json → manifest.panel: …) |
the worker is left out |
A modules: entry's manifest fails the same way |
kept with id and base, no manifest |
modules[i].dir has no module.json |
kept with id and base |
modules[i].id differs from the manifest's id |
kept with the declared id, no manifest |
Two modules with the same id |
the first in configuration order is kept |
| Two modules whose panels are the same page | both kept |
Two modules: entries with the same or nested base paths |
both kept |
A bundled manifest with kind: "worker" |
kept |
modules: entries but no core worker — they have no effect |
nothing is written |
ssg new worker <template> in a project that already has workers/core
prints one more line: how the new template joins the registry (listing it in
workers: for a Pages template, the modules: entry for a standalone Worker).
The registry is not part of site-graph.json or the ssg mcp site tools:
the graph is a public file, and the registry must not be.
Making your own worker a module
The full checklist — what a module must contain to work with core and with
auth — is MODULE-REQUIREMENTS. The steps below
cover the manifest.
-
Add
module.jsonat the root of the worker's directory, following the fields above. Start withcontract: 1,version: "1.0.0", your directory name asid, five-language texts,panel: nulland emptynav,permissionsandendpointsif it has no admin side. -
If it has an admin side, list one permission per level of trust (who may only look, who may change, who may do something irreversible or that reaches people) and add a
naventry per page worth a link. -
Serve the manifest at
…/api/module(or next to your admin route) behind the same check as the rest of your admin API, and declare that path asendpoints.manifest. A Pages Function imports a copy, as above. Optionally serve a summary at…/api/module/summarybehind the same check and declare it asendpoints.summary(see Adding a summary to your module). -
Check it: from an ssg checkout, the reader validates any manifest —
1node -e 'import("./workers/module-manifest.ts").then(async ({ readManifest }) => { 2 const fs = await import("node:fs"); 3 const r = readManifest(JSON.parse(fs.readFileSync(process.argv[1], "utf8")), 4 JSON.parse(fs.readFileSync("workers/module.schema.json", "utf8"))); 5 console.log(r.ok ? "ok" : r.errors.join("\n")); 6})' path/to/your-worker/module.json
Tests
1node --test 'workers/*.test.ts' # reader + every bundled template's manifest and summary
2go test ./internal/modules/ # the Go reader and the registry
internal/modules/testdata/manifests/ holds manifests with the exact errors a
reader must report for each; workers/module-fixtures.test.ts holds the
TypeScript reader to them and internal/modules/fixtures_test.go the Go one,
so the two cannot drift apart. After an intended change of a message,
UPDATE_MODULE_FIXTURES=1 node --test 'workers/module-fixtures.test.ts'
rewrites the expected errors.
The cross-template test treats every directory under workers/ that has a
functions/ tree or a wrangler.toml as a template and fails when one has no
manifest or an invalid one, when id is not the directory name, when kind
does not match the layout, when a panel, nav or endpoint path is not served
by the template's code (a file under public/, a Pages Functions route, or a
GET operation in a standalone Worker's openapi.yaml), or when a text lacks a
language. Each template with a manifest endpoint also tests that route against
its admin endpoint.