Guide

Workers, modules and services

SSG generates static HTML. The parts of a site that run per request — payments, forms, comments, a newsletter, accounts, editing in the browser — are worker templates that ship in this repository, plus two small services you run yourself.

The split is deliberate: SSG for content, workers for transactions. The content pages stay static (fast, cacheable, cheap); only the handful of /api/* routes and admin panels reach code. Every worker below is optional, and a site without any of them builds exactly as before.

Every worker and service in the repository

Sixteen worker templates under workers/ (each with a module.json that names and describes it) and two services under services/. Pages Function means the build copies it into the site through workers: and it deploys with the pages; standalone Worker means it has its own wrangler.toml and is deployed on its own from its directory; Docker service means a container you host. Sign-in modes are explained below.

Template What it does Runs as Admin panel and sign-in Read more
auth Accounts with passwords or login providers, revocable sessions, and short signed tokens the other workers verify with a public key Pages Function /auth/admin/; its own accounts: a password per person, Google, Microsoft, Apple, GitHub, Facebook or Cloudflare Access README, ADMIN-GUIDE
comments Reader comments in D1, protected by Turnstile and held for moderation Pages Function /comments-admin.html; Access, auth or password README
contact-form Receives a contact or job-application form, checks Turnstile, sends it by email through Resend or MailChannels Pages Function none README
conversions-proxy Relays conversion events to the Meta Conversions API; the token stays on the server, the email address is hashed Pages Function none README
cookie-consent A GDPR, ePrivacy and UK PECR consent banner: scripts wait for consent, rejecting is as easy as accepting, choices can be logged Pages Function none README
core The admin home page: lists the site's modules, checks which answer, gathers what needs attention, shares one navigation bar Pages Function /core/; Access, auth or password README, ADMIN-THEME
designer-ui The site's settings and theme files in the browser; each publication is one commit standalone Worker its own host or path; auth only README, DESIGNER
dynamic-price Current prices from a KV namespace or a pricing API, so a static page shows today's amounts Pages Function none README
ecommerce A shop for digital products: Stripe or PayPal checkout, VAT, invoices, download links; orders in D1, files in R2 Pages Function /ecommerce-admin/; Access, auth or password README, ACP, UCP
editor-ui The site's Markdown articles and images in the browser; each publication is one commit (or one MDDB write) standalone Worker its own host or path; auth only README, EDITOR
newsletter Newsletter or waitlist sign-up: addresses in D1, consent stored with its wording, one-click unsubscribe, optional double opt-in Pages Function no panel; an admin API (counts, CSV export) behind Access, auth or password README
newsletter-ui The sending side of the newsletter: panel, campaigns, a queued send engine, bounces and complaints, statistics standalone Worker /newsletter-admin by default; Access, auth or password README, SMTP-SERVER
rate-limit A request budget for every Function in the project, including ones added later (middleware) Pages Function none README, below
republish-trigger One authenticated webhook that starts a CI build on GitHub, GitLab or Gitea Pages Function none; a shared key or an auth service token README
stripe-checkout Stripe Checkout sessions for one-time payments and subscriptions, with webhook signature checks Pages Function none README
web-push Browser notifications for new posts: one button to subscribe, a call after each deploy announces new feed items Pages Function none; a shared key or an auth service token for sending README, web_push
services/smtp-relay A Postfix submission server with DKIM for the newsletter workers' SMTP transport Docker service (or a Raspberry Pi without Docker) none; SMTP logins README, SMTP-SERVER
services/tts-server A text-to-speech HTTP API (espeak-ng, Piper) for build-time MP3s of articles Docker service none; API keys, admin keys for voices README, AUDIO

The worker descriptions above are the English description of each module.json, shortened; the manifest also carries them in Polish, Hindi, German and French (WORKER-MODULES).

  • WORKERS-CONFIGURATION — the .ssg.yaml keys: worker:, workers:, modules:, web_push:.
  • WORKERS-SECRETS — every secret and variable, by template.
  • WORKERS-DEPLOYMENT — local development, the generated wrangler.toml, deploying, and set-ups that keep a Function from running.
  • SERVER-ENDPOINTS — endpoints:, small redirects, proxies and forms declared once and run by --http or compiled for a platform.
  • ADMIN-GUIDE — from one panel with a password to a team with accounts, a second factor and the admin home page; ADMIN-THEME — the panels in the site's colours.
  • WORKER-MODULES and MODULE-REQUIREMENTS — the module manifest, and what your own worker needs to join auth and core.

Scaffolding a worker

ssg new worker <template> drops a batteries-included, npm-dependency-free template under ./workers/<template>/ and prints the worker: block to add (or, for a standalone Worker, its deploy steps). It also writes the four files the templates' tests share — workers/module-manifest.ts, module-summary-kit.ts, module.schema.json and module-summary.schema.json — when they are missing, so a template's own tests pass in a project of its own. An existing copy is kept and, if it differs from this release's, named on stderr; stdout stays the worker: block.

1ssg new worker stripe-checkout

Each template ships a README.md listing the secrets it needs, and a module.json — its module manifest: name and description in five languages, admin panel, navigation, the permissions its admin surface distinguishes, and how to switch it off. comments, newsletter, newsletter-ui, auth and core also serve it at …/api/module behind their admin auth, and all but core a summary (counts, things that need attention, configuration problems) at …/api/module/summary. When core is among the site's workers, the build gathers the manifests into a module registry (WORKERS-CONFIGURATION).

Pages Functions vs a standalone Worker

Every template except newsletter-ui, editor-ui and designer-ui is a set of Pages Functions: a functions/ tree that the build copies into the site, deployed together with the pages by wrangler pages deploy, configured through worker:/workers: and a wrangler.snippet.toml that ssg new wrangler folds into the site's config.

newsletter-ui is a standalone Worker: it ships its own wrangler.toml (main = "src/index.ts") and is deployed on its own, from its directory:

1ssg new worker newsletter-ui
2cd workers/newsletter-ui
3# database_id = the same D1 id as the newsletter template
4npx wrangler queues create ssg-newsletter-send
5npx wrangler queues create ssg-newsletter-send-dlq
6npx wrangler deploy

It exists because Pages Functions only answer requests. They have no cron trigger and cannot consume a queue, and a newsletter campaign needs both: the cron starts scheduled campaigns, and the queue sends them in batches that survive a failure, can be paused and resumed, and end up in a dead-letter queue instead of disappearing. The two workers share one D1 database (NEWSLETTER_DB): newsletter owns subscribers, newsletter-ui owns its own tables and never changes that one.

For a template like this, ssg new worker prints deploy steps instead of a worker: block, and ssg new wrangler leaves it out of the site's wrangler.toml. Listing such a directory under worker:/workers: stops the build with an error. Copying it into functions/ would turn its sources and tests into public routes. The rule: a directory with a wrangler.toml, no functions/ and no pages_build_output_dir is standalone. A core worker learns about a standalone Worker from a modules: entry.

Bounding how often they can be called

Every template that writes something — sends an email, stores a comment, logs a consent — is a public, unauthenticated endpoint. Turnstile raises the cost of abusing one without capping it: a solved token can be replayed inside its validity window, and Turnstile is optional in the first place.

rate_limit / rate_burst in .ssg.yaml bound the built-in preview server only. rate-limit is the deployed counterpart:

1ssg new worker contact-form
2ssg new worker rate-limit
3cp -r workers/rate-limit/functions/_middleware.ts workers/contact-form/functions/

It is middleware, so it wraps whatever is in functions/ without either side knowing about the other. RATE_LIMIT_SKIP carves paths back out — the newsletter's one-click unsubscribe, POSTed by mailbox providers from a few shared addresses, is the case it exists for. Without a backend bound it is a no-op — a limiter that turns visitors away because nobody finished configuring it is worse than no limiter — and it fails open by default, which is right for a contact form and wrong for a checkout, so RATE_LIMIT_FAIL = "closed" is there for the latter.

Prefer the RATE_LIMITER binding over KV. KV is eventually consistent, so a burst arriving at several points of presence at once can overshoot the cap, which is exactly the shape a spam run takes.

Admin sign-in: which mode to choose

comments, newsletter, newsletter-ui, ecommerce and core have an admin side, and each offers the same three ways in. A worker uses the first one configured, in the order Cloudflare Access → auth → password; with none configured its admin routes answer 503, never open.

Mode Choose it when What you set
Shared password One person runs the site. The simplest setup, and fully supported: one secret per worker, nothing else to deploy <PREFIX>_ADMIN_PASSWORD (secret)
Cloudflare Access You already run Cloudflare Zero Trust and want your identity provider at the edge <PREFIX>_ACCESS_TEAM + <PREFIX>_ACCESS_AUD
auth Several people, several panels, or different permissions per person (a moderator who may not delete, an editor who may not send) deploy auth, then <PREFIX>_AUTH_ISSUER, <PREFIX>_AUTH_LOGIN_URL and <PREFIX>_AUTH_PUBLIC_KEY (or _JWKS_URL)

The prefixes are COMMENTS, NEWSLETTER (one set serves both newsletter templates), SHOP and CORE. Access and the password allow every action; with auth each action needs its permission, and the password is not accepted while any <PREFIX>_AUTH_* variable is set. Delete the password secret when you switch, so removing the variables later does not quietly bring it back. web-push and republish-trigger are called by machines: they keep their shared key and can also accept an auth service token.

editor-ui and designer-ui are the exception to the three modes: they accept only auth (EDITOR_AUTH_*, DESIGNER_AUTH_*), because every commit they make needs an author and a permission per action. Without a complete set they answer 503 on every path (EDITOR, DESIGNER).

A walk-through from one panel with a password to a team with accounts, a second factor and the admin home page is in ADMIN-GUIDE. The names of every secret are in WORKERS-SECRETS.

Tests

Templates with a test/ directory (auth, comments, contact-form, core, designer-ui, ecommerce, editor-ui, newsletter, newsletter-ui, republish-trigger, web-push) run with make test-workers, after the cross-template test of every module.json and summary (workers/*.test.ts) — Node 23.6 or newer, no npm packages. Pull requests that change workers/ run the same target in CI (the Workers workflow). The compat-* tests pin existing answers so an existing install keeps working: newsletter's every endpoint as in 1.9.7, comments' admin endpoints, web-push's notify and republish-trigger's key check as in 1.9.8.