The newsletter block sits in every content page footer. features.newsletter sets the mode:
'off', 'embed' or 'd1'.
-
Paste the provider’s form.
site.config.ts features: { newsletter: 'embed' },newsletter: {heading: 'New tools, weekly',blurb: 'One email a week. No spam.',embedHtml: '<form action="https://provider.example/subscribe" method="post"><input type="email" name="email" /><button>Subscribe</button></form>',},pnpm check:configanswerssite.config.ts OK — <name> (<url>). -
Build, and read the zero-JS line.
Terminal pnpm build -
Deploy:
pnpm deployor a push.
-
Switch the mode;
subscribersships in the migrationspnpm cf:setupran.site.config.ts features: { newsletter: 'd1' }, -
Deploy.
Terminal pnpm deploy -
Sign up from the footer; the URL gains
#newsletter-thanks.
Verify
Section titled “Verify”| What | Where | Expect |
|---|---|---|
| Block | any content footer | heading, blurb, d1 form or embed |
| Row | pnpm exec wrangler d1 execute DB --remote --command "SELECT count(*) AS n FROM subscribers WHERE unsubscribed_at IS NULL" |
n counts your address |
| Count | /admin/stats/ |
Newsletter subscribers — n/a unless d1 |
| Zero JS | build log | zero-js: <n> content pages, 0 islands, 0 external scripts — ok |
Worth knowing
Section titled “Worth knowing”-
embedrendersnewsletter.embedHtmlunsanitised; a<script src>fails the build:content pages must ship zero JavaScript. -
The form posts to
/api/newsletter/— the trailing slash matters,/api/newsletterearns a 308. The 303 reply carries#newsletter-thanks,#newsletter-invalidor#newsletter-unavailable. -
features.honeypotadds a hiddencompanyfield. -
No unsubscribe flow; the starter sends no newsletter. An address unsubscribed by hand stays unsubscribed:
ON CONFLICT DO NOTHINGskips existing rows.Terminal pnpm exec wrangler d1 execute DB --remote --command "UPDATE subscribers SET unsubscribed_at = unixepoch() WHERE email = 'gone@example.com'" -
Export the list (
created_atis unix seconds):Terminal pnpm exec wrangler d1 execute DB --remote --json --command "SELECT email, created_at FROM subscribers WHERE unsubscribed_at IS NULL ORDER BY created_at" > subscribers.json
When it is off or degraded
Section titled “When it is off or degraded”| State | Visitor sees | /admin/ reports |
Fix |
|---|---|---|---|
'off' (default) |
no block; /api/newsletter/ answers 404 |
stats: n/a |
— |
'embed', no embedHtml |
heading and blurb, no form | n/a |
set embedHtml |
'embed' with <script src> |
build fails | — | use a plain form |
| Honeypot filled | “Thanks — you are on the list.”; nothing stored | — | — |
| Bad address | “That does not look like an email address.” | — | — |
| D1 refuses the write | “Sign-up is temporarily unavailable.” | newsletter: signup failed in the Worker log |
wait, or Workers Paid |
Configuration
Section titled “Configuration”features.newsletter, features.honeypot, newsletter.heading, newsletter.blurb and newsletter.embedHtml — features, newsletter.
src/components/site/Newsletter.astro— the block, the three fragments, the honeypotsrc/components/site/Footer.astro— where it mountssrc/pages/api/newsletter.ts—handleSignup(), the 303src/db/schema.ts—subscriberssrc/templates/admin/StatsPage.astro— the subscriber countsrc/config/defaults.ts—DEFAULT_NEWSLETTERintegrations/budget.ts— the zero-JS check