Notable changes to the ZeroDirs Starter. The format follows Keep a Changelog, and versions follow Semantic Versioning as they apply to a codebase you own:
- Major — a change that will not merge cleanly into a customised copy, or that changes the
shape of
site.config.ts. - Minor — new features and new config fields, with defaults that keep existing sites building.
- Patch — fixes and documentation.
Quote the version below when you ask for support, and paste the full output of the failing
command. The version is also in package.json. Support: hi@zerodirs.com.
Three paths are yours and no release edits them: site.config.ts, src/content/ and
public/. Everything else is ours to change, so Changed and Removed entries are where
a merge conflict would come from —
zerodirs.com/docs/about/updates/ covers how to
apply one.
0.2.1 (unreleased)
Section titled “0.2.1 (unreleased)”Changed
Section titled “Changed”pnpm cf:secretsis one command, no prompts (design.md N74): it reads.env.prod, checks the shape of every value, sends all runtime secrets to the Worker in one request and reads back what the Worker has.--dry-runshows the plan without sending,--listshows the names, what yoursite.config.tsneeds and what is set, and bare names (pnpm cf:secrets STRIPE_SECRET_KEY) send only those — from.env.prod, no longer from a prompt.--allstill works and means nothing;--from-envand the fallback to.envare gone (test-mode keys must never reach production by accident). A key in.env.prodthat.env.exampledoes not know stops the run. To upgrade: nothing in your files changes; create.env.prodfrom.envif you have not, and drop--allfrom any note you kept.- The header, redrawn (design.md N68): the Submit call-to-action is a pill with a
paper-plane icon and the word “Submit” (its accessible name is still “Submit a {noun}”);
the search field is gone from the header — the home page carries the big one — and the
theme toggle and a new account icon sit to the right of the pill. The account icon links
to
/dashboard/and replaces the “Account” item in the nav; for a signed-out visitor it opens the sign-in dialog (next entry), and for a signed-in one it is their avatar, which opens a menu — name, address, Dashboard, Bookmarks, Log out (design.md N78). Content pages are static and identical for everyone, so the header learns who is signed in from a second cookie,zd_user, that holds a name, an address and an avatar URL and nothing a thief could use; the session itself stays in the HttpOnlyzd_session. To upgrade: add'send','user','layout-dashboard','bookmark','log-out'and'chevron-down'totheme.iconsinsite.config.ts; without them the pill shows only its label and the menu only its words, and nothing fails. - Signing in happens in a dialog (design.md N76): pressing the account icon opens the
sign-in card on the page the visitor is already on — email and password, “Continue with
Google” when both Google secrets are set, “Forgot password?” and “Don’t have an account?
Sign up” — instead of sending them to
/login/. A wrong password comes back into the dialog, with the address kept and the password field focused; a right one sends the visitor on to the page they were after, or to/dashboard/. The card is asked for when the dialog opens (/login/dialog/, rendered by the Worker), because a static page cannot know who is signed in or whether the Worker holds the Google secrets./login/stays — it is where/submit/and/dashboard/send a signed-out visitor, and what a browser without JavaScript gets — and is redrawn as the same card. It costs one more inline script on every page whilefeatures.accountsis on, about 2.6 KB; still no island and no<script src>, and the e2e smoke test counts it. To upgrade: take the merge. If you had editedsrc/templates/account/LoginPage.astro, its markup now lives insrc/components/account/AuthCard.astro; the three form-validation colours moved fromsrc/components/forms/Field.astrointosrc/styles/global.css. - Submitters sign in with a password, not an emailed link (design.md N77). An account is
made on
/signup/with an email and a password (eight characters or more), and signed in on/login/or in the dialog with the same; “Continue with Google” is unchanged. Passwords are stored as PBKDF2-HMAC-SHA-256 at 100,000 iterations with a per-password salt, in a form that names its own parameters, so the count can be lowered later (the free plan’s CPU budget is tight for it) without invalidating anything. The one emailed link left is “Forgot password?”:/login/forgot/queues a reset link that works once and for twenty minutes,/auth/reset/is where it lands, and thepassword-resetemail template replaceslogin-link. Ten wrong passwords in a quarter of an hour lock the address for the rest of it; the form says “wrong email or password” and nothing more, whichever it was. Nothing checks the mailbox at sign-up, so an address is only proven by a Google sign-in or a completed reset — and the first time it is proven, a password somebody else registered for it is dropped, with its sessions: the mailbox’s owner gets the account, and sets a password of their own through the reset link. To upgrade:pnpm db:migrate:local, thenpnpm db:migrate:remoteonce (0002_passwords.sqladds two columns tousersand marks every account that exists as proven). Accounts made under 0.2.0 have no password: Google keeps working for them, and “Forgot password?” sets one.requestLoginLink/consumeLoginLinkare gone fromsrc/server/auth/;/auth/callback/with it. /account/is now/dashboard/(design.md N78, N79), an area of its own with a sidebar — Overview, Submissions, Bookmarks under Dashboard, Account under Settings, then Visit site — and a top bar with the Submit button, the theme toggle and the account menu. The sidebar folds to a rail of icons on a wide screen (every icon is still the link, with its name as the tooltip) and stays folded from page to page through azd_railcookie; on a phone it is a drawer. Overview: four numbers (submitted, live, in review, clicks in the last 30 days) and a table of every submission that?q=searches by name or host and?sort=/?dir=order by name, status, clicks, submission or publication date — plain links and a GET form, no script. Submissions: the same rows under tabs, with what can be done about each — Upgrade a submission waiting in the free queue onto a priced plan (a popover with the plans, each leading to its checkout), Complete payment, View, Submit again, and Withdraw a submission that is still waiting and not paid for: it asks once, then the submission becomes “Withdrawn” (stored asrejectedwith the reasonWithdrawn by the submitter., so the operator sees why it left the queue; no email) and the address is free to be submitted again. Account: the avatar, address and sign-up method with a Log out button, the name, and the password — change it with the current one, or set a first one on an account that has only used Google; either signs out every other device./account/answers with a permanent redirect to/dashboard/, anddashboardjoins the reserved route segments and therobots.txtdisallow list. To upgrade: take the merge; add'zap','arrow-up','arrow-down','chevrons-up-down','panel-left','lock'and'calendar'totheme.icons(each is optional, like the others); aroutes.*Basenameddashboardhas to be renamed, whichpnpm check:configwill say. Thesrc/templates/account/AccountPage.astroof 0.2.0 is gone; the dashboard’s pages aresrc/templates/account/Dashboard*.astroonsrc/layouts/Dashboard.astro.- ⌘K / Ctrl K opens a command palette on every page: a search field, the site’s quick
links and its featured listings (logo, name, host), filtered as you type; Enter runs the
full search on
/search/. The⌘Kbadge in the home-page search field opens it too, and reads Ctrl K off a Mac. It is a native<dialog>with server-rendered rows and one inline script of about two kilobytes — no island, no<script src>, so rule 17 still holds and the e2e smoke test counts it.theme.iconsshould listsearchandxfor its two icons (the demo config already does). - The first
pnpm devof a fresh clone takes about twenty seconds instead of three and a half minutes, andpnpm content:reset --locala few seconds instead of the same. Every logo used to go into the local bucket through its ownwrangler r2 object put --local(and out through its owndelete), 1.5 s of wrangler start-up per object; against--localthe seed and the reset now open the bucket binding once in-process, through wrangler’sgetPlatformProxy(), and put concurrently or delete in one batch. Downloads run sixteen at a time instead of eight, and a host that has not answered in five seconds is a letter tile rather than a twelve-second wait.--remoteis unchanged: one wrangler process per object, no S3 credentials needed.
/signup/, a create-account page (design.md N76, N77), where the sign-in dialog’s “Sign up” leads: a name (optional, it ends up on the account), an email and a password, or Google when it is configured, with the terms and privacy pages linked whenlegalhas them.signupjoins the reserved route segments and therobots.txtdisallow list. To upgrade: aroutes.*Basenamedsignuphas to be renamed, whichpnpm check:configwill say.- Bookmarks (design.md N79): a Bookmark button on every listing page, under “Visit”, for
a signed-in visitor — pressed, it saves the listing in place and reads “Bookmarked” from
then on; pressed by a signed-out visitor it opens the sign-in dialog and comes back to the
page.
/dashboard/bookmarks/lists what was saved, newest first, with Open and Remove. The button is a form that works without JavaScript (the post lands on the bookmarks page), plus one inline script of about 0.8 KB on listing pages only, which asks/api/bookmarks/<id>/whether the listing is saved — a static page cannot know — and posts to it withfetch. To upgrade:pnpm db:migrate:local, thenpnpm db:migrate:remoteonce (0003_bookmarks.sqladds thebookmarkstable).features.accountsoff leaves the button out; there is no flag of its own. A seed orpnpm content:usekeeps bookmarks: seeded listings keep their ids, and a bookmark whose listing is gone is simply not shown.
- A submission that was refused — or, now, withdrawn — could still be paid for: its status
page kept its “Complete payment” button, and
/api/checkout/took the money for a listing that would never be reviewed. Both now apply to a pending submission only. - The Google sign-in failed with “Sign-in did not complete” on every attempt: the OAuth state
cookie was URL-encoded twice on the way out and never matched on the way back. The reason
a Google round trip declines is now logged (
auth: Google sign-in did not complete — …), so a wrong client secret or an unregistered redirect URI can be told apart from a refused address. Underpnpm devthe redirect URI is the local origin (http://localhost:4321/auth/google/callback/), so “Continue with Google” can be tried locally with that URI registered as a second one. - Deploys no longer fail with “required secrets have not been set” (design.md N75). Since
0.2.0,
wrangler.jsonclisted every runtime secret undersecrets.required, andwrangler deployrefuses to deploy while any of them is missing on the Worker — sopnpm cf:setup(which has to deploy once before it can put a secret), Workers Builds and the GitHub Actions workflow all failed for a site that leaves an optional provider off. Thesecretsblock is gone fromwrangler.jsoncaltogether: an empty list would unblock the deploy, but anysecretsblock makes wrangler hand the local Worker only the names it lists, andpnpm previewwould run without the secrets in your.env. What the list was there for — aworker-configuration.d.tsthat does not depend on your.env— is nowpnpm cf:typegenreading the names from.env.example(wrangler types --env-file .env.example); CI checks withpnpm cf:typegen --check. To upgrade: take the merge; if you had added asecretsblock or names of your own, remove them, and usepnpm cf:typegenrather than a barewrangler types.Envnow lists every key of.env.example, the four build-time ones included. One thing the list did by accident is now done by name:astro previewreads its secrets from the build’s snapshot of.env(dist/server/.dev.vars) or fromprocess.env, never from the.envfile itself, so a build made before.envexisted served a Worker with noTOKEN_SECRET;integrations/preview-secrets.tssets wrangler’sCLOUDFLARE_INCLUDE_PROCESS_ENVforpreview, andpnpm test:e2erebuilds when.envis newer thandist/. - The first
pnpm devof a fresh clone exited withThe file does not exist at "node_modules/.vite/deps_ssr/handler-….js"; the second one worked. Vite discovered the preact renderer’s server entry on the first request, re-optimized the SSR dependencies and reloaded, and the Cloudflare plugin’s worker was still holding the chunk that had just been replaced. The entry is now pre-bundled at startup, and CI starts the dev server on a cold cache and fails when it does not answer.
0.2.0 — 2026-09-22
Section titled “0.2.0 — 2026-09-22”Changed
Section titled “Changed”- One environment file. Build-time variables and runtime secrets now share
.env, with.env.exampleas the committed key set and.env.prod(gitignored) as what production gets..dev.varsis gone: wrangler reads it in preference to.env, so keeping both meant a stale file could silently shadow every secret you edited. To upgrade:cat .dev.vars >> .env && rm .dev.vars, thenpnpm cf:typegen.pnpm devrefuses to start while a.dev.varsis still there, and prints that same line.wrangler.jsoncnow declaressecrets.required, sowrangler typeswrites the sameEnvon every machine and CI no longer seeds a secrets file before checking the committed types. - Listings always come from D1. Every build reads the database: with the three D1
credentials set (
CLOUDFLARE_ACCOUNT_ID,D1_DATABASE_ID,D1_READ_TOKEN— a production builder) the real one over its REST API, exactly as before; with none of them set (your machine, CI) the local Miniflare database under.wrangler/, throughwrangler d1 execute --local. A partial set fails the build and names the rest, and a builder that has lost its variables has no local database either, so it fails instead of shipping the seed listings as a success.pnpm devseeds the local database with the demo dataset — rows and logos — the first time it finds it empty, and never touches a database that holds anything. A local build links every logo through the/media/route, which the Worker now serves in every environment (production links keep usingmedia.baseUrl), and the OG images of a local build carry no logo. Outbound click counting therefore works in every build: every listing has a row id. To upgrade: listings you kept insrc/content/listings/go into the database once —pnpm db:seed:local --from src/content/listings, then the same with--remote— and the directory,public/logos/,LISTINGS_SOURCEandZERODIRS_DATASETcan go; a Workers Builds or Actions setup that built from Markdown now needs the three credentials.pnpm cf:doctorsays which database a build here reads. pnpm content:resetandpnpm content:useact on a database (--localby default,--remote):resetdeletes the seeded rows, their logos in the bucket and the demo blog posts and leaves the database empty;use <dataset>seeds it with a dataset and copies the dataset’s blog posts.pnpm listings:importwrites to a database (--localor--remote, one is required unless--dry-run) and no longer to Markdown files;pnpm check:configcounts the approved rows in the local database for its estimate.pnpm cf:setupfinishes the email step instead of only reporting it: withproviders.email: 'cloudflare'and no sending domain it offerswrangler email sending enable <domain>, keeps theEMAILbinding when that works, and puts the binding back on a later run once the domain exists — previously the binding was dropped and had to be restored by hand.- The default look, redrawn (design.md N51): a search-first home page with the category chips
under the field, cards led by a logo tile with the name over its category, a browse strip of
category chips on the listing index and category pages, a sticky facts card with the outbound
button on the detail page, a stepper and option cards on the submission form, a four-tile
queue summary on the admin dashboard, and a sticky translucent header with a Submit button on
every page. Still zero JavaScript. The tokens are the same fifteen;
default’sradiusmoves from0.5remto0.75rem, and cards, buttons and chips are now fixed multiples of it (rounded-brand-lg,rounded-brand-pill), somonostays square andwarmrounder with no new knob. Three component classes join.btnand.card:.chip,.input,.hero-glow. A copy that overridesradiusgets the same proportions at its own size; one that editedCard.astro,Detail.astro,Header.astro,Footer.astroorHomePage.astrowill merge by hand. - Paid plans ship on:
features.payments: true,providers.payment: 'stripe'and both priced tiers enabled insite.config.ts, the way the demo runs. The two Stripe secrets are yours to set (pnpm cf:secrets STRIPE_SECRET_KEY STRIPE_WEBHOOK_SECRET); until they are on the Worker a paid submission’s checkout answers 503 “Payment is temporarily unavailable”,/admin/reports both keys, and the free plan keeps working. - Email ships on, through Cloudflare Email Sending:
providers.email: 'cloudflare'insite.config.tsand theEMAIL(send_email) binding declared inwrangler.jsonc. It needs the Workers Paid plan and a sending domain enabled on your zone; until both are true every message still renders intoemail_outboxand/admin/says why. On the Free plan, switch to Resend — the skill walks through it. - The README troubleshooting section names the
npm installcrash of npm 11.4 (Node 24.3) on vitest 4’s peer dependencies and the three ways out; pnpm is unaffected. pnpm cf:secretsis a conversation now. It starts by listing which secrets the deployed Worker already has, shows each key’s help text line by line (every key in.env.examplenow says where its value comes from), takes names as arguments (pnpm cf:secrets STRIPE_WEBHOOK_SECRET), checks the shape of a value before uploading it — awhsec_pasted intoSTRIPE_SECRET_KEY, the placeholderTOKEN_SECRET, a publishable key — and asks before going ahead, and ends cleanly on Ctrl+C with what was set and what is still missing. Every prompt also says whether the currentsite.config.tsneeds that secret at all (a GitHub token is idle on a site that publishes through a deploy hook). Wrangler’s banner no longer interleaves with the prompts.- The demo’s top banner (
ads.topBanner) is a house ad for ZeroDirs: on your own site, give it your sponsor’s text andurl, or setenabled: false. - pSEO, the OG images and the related-listings ranking moved to
src/features/pseo/,src/features/og/andsrc/features/related.ts, andsrc/features/index.tsis gone. Templates and components import those modules directly, and each entry function checks its own flag (pseoPages()readsfeatures.pseo,relatedListings()readsfeatures.relatedLinks) and takes the config as an argument. A copy that edited one of these files merges it as a rename; one that imported fromsrc/features/index.tschanges that import. The hard rules inAGENTS.mdare renumbered.
pnpm cf:media: the one steppnpm cf:setupcould not finish. It makes the R2 bucket readable from the web — a custom domain when you have the zone id, ther2.devURL otherwise — and writes the result intomedia.baseUrl, restoringsite.config.tsuntouched if the edited file does not validate.pnpm cf:doctor: one read-only screen for “is this actually wired up?”. It checks the tooling,site.config.ts,wrangler.jsonc,.env, which secrets the Worker holds, the R2 bucket and sending domain, and whether the live site was built with the config you have now — each line either✔or a problem with the command that fixes it. It writes nothing, and a check it cannot make (no login,--offline) says so instead of guessing.--jsonfor an agent,--strictto fail on warnings,--manualfor the steps no CLI can do.pnpm cf:secrets --all: every runtime secret in.env.prod(or.env) in onewrangler secret bulk, values on stdin. Empty, placeholder and wrong-shaped values are left out and named, so a truncated paste cannot reach the Worker.--dry-runlists what it would send without sending anything.pnpm cf:ci: the build-time half of the same file pushed to GitHub Actions withgh variable set/gh secret set, and the Build step’senv:block in.github/workflows/deploy.ymlrewritten from.env.examplebetween marker comments, so a variable you add is never missing in CI.--enablesetsUSE_GITHUB_DEPLOY.pnpm cf:setup: from a checkout to a running site in one command — Worker name, custom domain or*.workers.dev, D1 and R2 created and written intowrangler.jsonc, thesend_emailbinding left out until the account can send, production migrations, build, deploy, andTOKEN_SECRET. Idempotent, with--dry-runand--workers-dev.pnpm dev(andpnpm test:e2e) now runsscripts/dev-setup.tsfirst:.envfrom its example when missing, the D1 migrations applied to the local database, and the demo dataset seeded into it while it is empty — so a fresh clone reaches/,/submit/and/admin/on its firstpnpm devwith no Cloudflare account.- A
go-liveskill: the stepscf:setupleaves to you — domain, the real database for the builder, Workers Builds and the Deploy Hook, email, payments — one question at a time. - Submitter accounts (
features.accounts, on in the demo): sign in with an emailed link that works once for twenty minutes, or with Google onceGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETare set;/account/lists a submitter’s own submissions with their review status;/submit/requires a session and takes the address from it. Sessions are 30-day cookies whose ids are stored hashed; the hourly cron sweeps what expired. One expand-only migration (0001_accounts.sql) addsusers,sessions,login_tokensandlistings.user_id. Theconfigure-accountsskill has the Google steps. Ten skills. - Ad placements, each one boolean in the new
adsblock: a banner under the header, a sponsor wall under the home page hero, a card inside every listing grid, and a corner card that can be dismissed without JavaScript./advertise/lists the placements and their prices and is built only whileads.page.enabled. Everything is static and marked as an ad (rel="sponsored"); the demo shows all four with placeholder copy. - The free review queue says how long it is. A free submission’s status page and receipt
email state when it is expected to go live — position in the queue divided into the last
30 days of real approvals, or
queue.estimateDays(21) while there are none — and offer the priced plans to skip ahead: one click to Stripe Checkout, and the tier changes only once the payment lands. The operator gets one reminder a day atqueue.digestHourUtc(09:00 UTC) while anything is waiting, with the oldest wait and the paid submissions close to their review promise;nullswitches it off. The admin dashboard shows the same numbers. site.builtWith(defaulttrue): a “Built with ZeroDirs” link in the footer, one boolean to remove. Not a licence condition.- A
configure-emailskill: the three email providers side by side, the Cloudflare Email Sending path, the Resend path for the Workers Free plan, and how to verify with the outbox and the/admin/configuration report. tests/unit/put-secrets.test.ts: the pure parts ofpnpm cf:secrets— the help text every key gets, name selection, and each shape check, including that no check ever repeats the value.
Removed
Section titled “Removed”.dev.varsand.dev.vars.example. See the.enventry under Changed.- Markdown as a listings source:
src/loaders/files.ts,src/content/listings/(a copy of theai-toolsdataset),public/logos/(its 14 tiles, still inseed/datasets/ai-tools/logos/), theLISTINGS_SOURCEandZERODIRS_DATASETbuild variables,pnpm content:check, andpnpm listings:import’s--out/--to. See the D1 entry under Changed for the one-time move. docs/. The documentation is the site at zerodirs.com/docs, which is generated from the code and cannot drift the way the copies here did, and nothing in the starter links to the old files any more. Their text is in the git history (git log -- docs/). If your copy edited a file underdocs/, the merge reports a modify/delete conflict: keep the file or delete it, nothing reads it.
- The submit Action built its email provider without the Worker’s bindings, so with
providers.email: 'cloudflare'the console provider “sent” every receipt: the outbox rows were markedsent, nothing left the account, and no error was raised anywhere. Both Actions and the cron now handenv.EMAILover through one helper, and a unit test fails if any of them ever builds a provider without it. features.search: falsefailed the build:/search/was still built, island included, but had left the routes manifest, so the zero-JS check no longer exempted it. The page now returns a body-less 204 while the feature is off, the way/blog/does, and no file is written.- The search panel’s message under
pnpm devsaid a build alone would enable search there; it ispnpm buildand thenpnpm preview. LICENSE§5 saidpnpm content:reset --yesremoves the demo datasets. It removes the demo listings, the demo posts and the files inpublic/logos/, and leavesseed/datasets/in place; the licence now says so. Comments that miscounted the runtime secrets or the hourly jobs (.env.example,scripts/put-secrets.ts,wrangler.jsonc,src/worker.ts,src/server/jobs.ts,AGENTS.md) are corrected too.- The
import-listingsandgenerate-listingsskills said a numeric custom field does not render and told the agent to quote it. Numbers and booleans render; only arrays and objects are dropped, which is what both skills now say.
0.1.0 — 2026-09-13
Section titled “0.1.0 — 2026-09-13”The first buyer release. Everything listed here works today. Several subsystems ship switched off because switching them on needs a database or a credential we cannot put in a repository — the README’s “What’s on, what’s off” table says what each one still needs.
Directory core
- Listings, categories, tags and pagination from Markdown in
src/content/listings/, one file per listing, validated againstsite.config.tsat build time. - One catch-all route builds every directory page from a pure, unit-tested route table, so the
URL segments (
routes.listingBase,categoryBase,tagBase) are yours to rename. - Related listings on every detail page, and configurable per-listing custom fields.
- Full-text search over listing pages (Pagefind), indexed during the build.
/search/is the only page in the site that hydrates. - Blog with its own feed at
/blog/rss.xml, a site-wide latest-listings feed at/rss.xml, and about, privacy, terms and 404 pages.
Submissions, moderation and payments (features.submissions, features.payments)
- A public two-step submission form that prefills itself from the submitted site’s own metadata, a honeypot trap, per-email rate limiting, and a signed, token-addressed status page that needs no account and no password. The submitter never sees the word “logo”: the prefill ranks every icon the page declares, and the server downloads them in order until one is storable.
- An admin area — review queue, listing editor, featured placements and stats — open to the
accounts named in
admin.emails, with a Publish button and an optional rebuild on approval (providers.rebuild: Cloudflare Deploy Hook or GitHubrepository_dispatch). - Stripe checkout for priced tiers, a signed webhook that records the payment idempotently, and an hourly cron that sweeps unpaid submissions, retries the mail outbox and expires featured placements.
- Transactional email through Resend, Cloudflare Email Sending or a console provider, every
message rendered into an
email_outboxtable first so nothing is lost to a failed send. - Outbound click counting at
/out/<id>/—<a ping>by default, so the listed site keeps the link it was sold — and self-hosted newsletter capture into D1. - A D1 schema with drizzle-kit migrations, a build-time D1 REST loader (
LISTINGS_SOURCE=d1), and seed/export scripts in both directions between Markdown and the database. pnpm db:seed --with-imagesstores the dataset’s own logos in your R2 bucket — an absolutehttps://URL in the frontmatter is downloaded, a/logos/file is uploaded — and--with-faviconsfetches the icon each remaining site publishes about itself, so moving from Markdown to D1 does not lose a picture the Markdown named. Afavicon.icois decoded to the PNG of its largest frame, in plain TypeScript, so most entries come back with a picture; sites that block crawlers keep the initial-letter tile. Every object carries a five-minutecache-control, so a re-seed shows within minutes and needs no cache purge.
SEO
- Programmatic SEO pages from two configurable patterns (
best-category-for-tag,name-alternatives), with a thin-content guard, a page cap, and per-page copy overrides fromsrc/content/pseo/. The demo data generates 211 of them. - Open-graph images rendered at build time with satori + resvg, one per listing and category,
in your theme’s colours; plus a regenerable static fallback (
pnpm og:default). - Chunked sitemap,
robots.txt, canonical URLs, JSON-LD (breadcrumbs, item lists, organization, and a listing type chosen fromsite.kind), and anoindexrule for thin taxonomy pages. - A build-time SEO report that counts inbound internal links per listing and can fail the
build on orphans (
seo.strictLinks).
Configuration and theming
site.config.tsas the single configuration surface, zod-validated with ten cross-field rules, every error reported assite.config.ts › path: message.- Three theme presets (
default,warm,mono), 14 CSS tokens overridable from the config, dark mode with a no-flash bootstrap, and self-hosted web fonts via Astro’s font pipeline.
Tooling
pnpm check:config— validate the config and estimate the static-file budget before building.pnpm content:reset/content:use/content:check— swap between the demo dataset and examples generated from your own categories.pnpm listings:import— CSV or JSON to Markdown, with column aliases,--mapoverrides and a--dry-runthat reports every bad row at once.- A static-file budget check that warns at 80% and fails the build at 90% of the Cloudflare plan limit, so an over-size version is stopped locally rather than rejected at deploy.
- 857 unit tests (
pnpm test), 379 more inside workerd against a real D1 (pnpm test:workers), 30 Playwright tests over the built site (pnpm test:e2e), and a Lighthouse CI config that audits one page per template from your own route manifest (pnpm lhci), asserting ≥ 0.95 in all four categories.
Deployment
- Static output to Cloudflare Workers assets.
pnpm deploybuilds and uploads. A Worker script rides along for the on-demand routes and the hourly cron, but ships with noDBorMEDIAbinding and no secrets: with the default flags nothing reaches it, and a first deploy provisions nothing.
Shipped switched off
Section titled “Shipped switched off”Built and tested, off by default. Each needs something this repository cannot carry for you:
- Submissions and the admin queue (
features.submissions) — a D1 database, theDBbinding, andpnpm db:migrate:remote. - Payments (
features.payments+providers.payment: 'stripe'+ the priced tiersenabled) —STRIPE_SECRET_KEYandSTRIPE_WEBHOOK_SECRET. Cross-rule 3 requires all of them together, so a priced tier cannot be enabled with payments off. - Self-hosted newsletter (
features.newsletter: 'd1') — the sameDBbinding.features.newsletter: 'embed'needs nothing but your provider’s HTML. - Rebuild on approval (
providers.rebuild) — a Deploy Hook URL, or a GitHub token and repo. With'none', approved listings go live on your nextpnpm deploy. - D1 as the build’s data source (
LISTINGS_SOURCE=d1) —CLOUDFLARE_ACCOUNT_ID,D1_DATABASE_IDand a D1 Read token. Until then the build readssrc/content/listings/. - Transactional email (
providers.email: 'resend') —RESEND_API_KEYand a verified sending domain. Without it every message still renders, into the log andemail_outbox.
Known limitations
Section titled “Known limitations”- Firefox does not send
<a ping>at all, sofeatures.clicks: 'ping'undercounts its visitors;'redirect'counts them all at the cost of the link equity. - A local build’s OG images carry no logo. They link logos through the
/media/route, i.e. the local bucket, which the build cannot read; a production build fetches them frommedia.baseUrlas before. listing.screenshotMaxandlimits.screenshotMaxBytesvalidate but nothing reads them: every entry in a listing’sscreenshotsarray renders, and nothing in the app uploads one.
Requirements
Section titled “Requirements”Node 24 (.nvmrc), pnpm 10.12.4 (packageManager), Astro 7.3.1, wrangler 4.131.1.
Related
Section titled “Related”- Updates: how to pull a release into a customised copy.
- What you are buying: the product the versions above describe.