site.config.ts carries roughly 80% of the customisation. It is TypeScript, not JSON or YAML.
import { defineSiteConfig } from './src/config/define';
export const siteConfig = defineSiteConfig({ site: { /* … */ }, routes: { /* … */ }, categories: [ /* … */ ], tiers: [ /* … */ ],});Every field, its type, default and validation message: the configuration reference.
Four required blocks
Section titled “Four required blocks”site, routes, categories and tiers. Every other block is optional: delete it and its
defaults apply.
Reading an error
Section titled “Reading an error”$ pnpm check:configsite.config.ts is invalid (3 issues):site.config.ts › site.description: must be at most 160 characters (home meta description)site.config.ts › routes.listingBase: "blog" is a reserved path segmentsite.config.ts › tiers[1].featuredDays: required when kind is "featured"Cross-field rules
Section titled “Cross-field rules”These rules live in crossRules() in src/config/schema.ts and run after the whole object has
parsed and defaults have been applied — a rule can fire on a field you never set.
| Fields | Rule |
|---|---|
routes.*Base |
Pairwise distinct, none a reserved segment. blog and search are the two people hit; full list in the reference |
| Slugs and ids | Unique inside their own array, and none is page — reserved for pagination, it collides with /categories/page/2/ |
tiers |
At least one enabled. kind: 'featured' requires featuredDays, every other kind forbids it. A price above zero on an enabled tier requires features.payments and a payment provider |
| pSEO templates | Each id registered and used once, its placeholders known, maxItems ≥ minItems |
| Theme tokens | Raw CSS, not Tailwind class names, and no ;, } or < |
theme.font.preloadWeight |
One of theme.font.weights |
seo.templates |
Every placeholder is a known token. providers.emailFrom is present and well-formed unless the email provider is console |
site.url, media.baseUrl |
https://, with no trailing slash |
listing.customFields[].key |
Unique, and does not shadow a built-in listing column. A select field has options |
| Static-file budget | In src/lib/budget.ts, printed by pnpm check:config and the build. See Cost and limits |
Worth knowing
Section titled “Worth knowing”defineSiteConfig()mergescategories[].iconintotheme.icons, then deep-freezes the config.features.*is off unless the code behind it works — a flag needs a D1 database or a Stripe key first. A fresh clone builds with no account.seo.strictLinksdefaults tofalseand the demo sets ittrue. With it on, the build fails when a listing has fewer than two inbound internal links. Nothing else reports an orphan page.
What does not belong in this file
Section titled “What does not belong in this file”Secrets, and build-time variables. site.config.ts is committed, and a test greps it for
secret-shaped values.
.env— build-time variables (theD1_*group) above the marked line, runtime secrets below it.pnpm devwrites it from.env.example..env.prod— the same keys with production values.pnpm cf:secretsputs the secret half on the Worker,pnpm cf:ciputs the build half in CI. The static build needs none of the secrets.
A public astro:env field is inlined into the bundle at build time, so anything that must stay
secret has to be a server secret read at request time.
Environment and secrets has the table.