website-build-kit

Your build was green. The site was wrong.
nurkamol.github.io/website-build-kit

A method and a starter for shipping production marketing sites: discovery → stack and provider decisions → build → verify against the deployed thing → hand over.

Not a theme. The value is the accumulated set of decisions and the list of things that fail silently — clean build, clean types, clean deploy, wrong result.

/plugin marketplace add nurkamol/website-build-kit
/plugin install website-build@website-build-kit

Or clone and symlink, if you would rather not add a marketplace:

git clone https://github.com/nurkamol/website-build-kit.git
cd website-build-kit && ./install.sh

Then, in any project, just ask:

Rebuild https://acmeplumbing.com on Astro and Cloudflare.
We're migrating off Elementor — here's the site: https://example.com
Build a marketing site for a dental practice. Nothing exists yet.

The skill matches on description, so there is no command to remember. /website-build <url> works too if you want to be explicit.

→ docs/walkthrough.md — a worked example as a session, start to launch

→ docs/how-to-start.md — the three entry points, what to have ready before you begin, and what the first ten minutes should look like.

What's in it

The references

The skill loads these as needed rather than all at once.

traps.md is the one that earns its keep. Everything in it cost real debugging time.

Defaults

Astro static → Cloudflare Workers → worker assets (R2 past ~15 MB)
→ PagesCMS → Brevo → KV → GA4 or Cloudflare Web Analytics → Turnstile

Chosen because they are light, cheap at this scale, and compose without glue. Every one has alternatives in stacks.md with the specific condition that would justify switching.

The template

It arrives with no palette, no typeface and no home page. That is the design, not an omission: a starter that ships a look gives every site built from it the same one. What it does ship is the skeleton of the parts that take longest to get right:

• Media pipeline — npm run media: sharp → responsive AVIF and WebP, dimensions manifest so nothing shifts, favicons rendered from the vector, JPEG social twins only for images used as og:image. AVIF is 26% smaller at better quality, measured rather than asserted
• Design tokens — colour, fluid type scale, spacing, radii, tinted shadows, motion; plus a semantic layer so .on-dark inverts a whole section by redefining six variables. The brand ramp is a grey placeholder behind an --unset marker; you decide it
• npm run tells — the checkable half of design.md §3 against your own work: measure, section rhythm, the three-card grid, face pairing, headline size, motion duration, focus ring, raw hex in components. No browser, so it runs in CI. build:production refuses while anything is left undecided
• Form endpoint — server-side validation with field errors, honeypot, KV written before the email provider is called, and a no-JavaScript path that still works
• Token-protected CSV export of leads
• Environment derivation — one build variable decides noindex, analytics, canonical host, which store leads land in, and who gets notified
• Build guard that refuses any build without an environment, because a bare build publishes localhost canonical tags cleanly and with no error. It keys on the command, not on CI — npm run build is the most reflexive command in npm, and that is exactly where the hole was
• SEO — canonical, OG, JSON-LD built from the same data file the UI reads
• Header, footer, contact form, page opening, CTA — structure and behaviour, not styling: a mobile menu that replaces the header rather than layering under it, a focus trap, a sticky close control, and every interactive state a control needs
• Accessibility statement page — a required published artefact under the EAA and PSBAR — plus npm run a11y over one URL per template family
• npm run reflow — WCAG 1.4.10 and 1.4.4 against the deployed site: 320px wide and text at 200%, naming the widest offending element rather than reporting the page as broken. It is what keeps the testing claim on /accessibility honest — on one build that sentence was true when written and false a day later, because a redesign rebuilt every route
• npm run a11y:evidence — the dated evidence pack, written to a file instead of dying with the terminal scrollback. It writes the manual layers in as unchecked every time, because automated tooling catches roughly a third of issues and a pack that listed a clean run and stopped would read as a finished audit
• npm run recon — inventory the OLD site before designing routes: URLs from the sitemap plus the ones only the Wayback Machine remembers, which sitemap filename is canonical, preserved paths, and the integrations in the markup
• npm run extract — turns the captured HTML into clean markdown, one file per page, with frontmatter and portable image paths. It uses a real HTML-to-markdown converter rather than stripping tags, because html.replace(/<[^>]+>/g, '') glues a heading to its paragraph wherever the source was minified — right on the pretty-printed pages, wrong on the rest. It also flags what needs a person: heading levels the page builder used as type styles, alt text generated from the filename, and pages thin enough to suspect the capture
• npm run redirects — proposes a redirect map from the old inventory against the new routes, and never writes public/_redirects. Slug similarity is a guess, and a wrong 301 is worse than a 404: the 404 turns up in the log and gets fixed, the wrong redirect looks like it works
• npm run verify — the runbook's verification matrix as a gate that exits non-zero, run against the deployed site. Routes, a real 404, every redirect rule and whether its target resolves, security headers, the form submissions the API is meant to refuse, plus page weight and render-blocking counts — bytes and counts, never a timing, because a hand-rolled number from one machine disagrees with Lighthouse and nothing tells you it is wrong
• npm run check:secrets — compares the secrets your code declares in .dev.vars.example against what the deployed worker actually holds, and runs automatically at the end of deploy:staging and deploy:production. A missing one never throws: secret() returns undefined, the form still validates, still stores the lead, still returns 200 and still thanks the visitor — it just emails nobody. That is weeks of enquiries found by someone asking why the phone stopped ringing
• npm run shots — before/after screenshots of a migration at a mobile and a desktop width, paired into one page. Both sides read the same URL inventory, so a page that did not survive shows as a 404 beside its old screenshot. Take the before pass while the old site is still up; once DNS moves it is gone
• Legal pages as content — src/content/legal/*.md served through one route, with the footer links derived from the collection itself. A footer link to a page nobody has written yet is a 404 on every page of the site, and nothing reports it
• npm run console — console errors and failed requests on the deployed site, in a real browser. verify uses only fetch and so can never see this: the page returns 200, the HTML is correct, and something inside it failed after the response was complete. A blocked third-party script, a CSP violation or a 404 asset is invisible to a status-code sweep
• Build guards — check-env refuses a build whose environment disagrees with the routes in wrangler.jsonc; check-sitemap fails a production build when a URL is both in the sitemap and noindex
• npm run dns — snapshot the zone before you move the apex, and diff it after. Moving a domain without carrying MX kills the client's email, and it fails silently: the bounces go to the sender, so the people who find out cannot tell the client
• Staging is marked and blocked — a standing badge on every non-production build that reads the live DOM and alarms when the page disagrees with its environment, plus X-Robots-Tag on every response, which is the only one of the three controls that covers a PDF
• npm run cards — one 1200×630 JPEG Open Graph card per page, picked up automatically from the canonical path. JPEG because Facebook and LinkedIn still fail to render a WebP og:image and no scraper accepts SVG — a shared post would unfurl with no picture at all. The generator ships; the card design is a stub, so it renders nothing until you decide it
• npm run lastmod — per-route content dates for the sitemap, computed by a human with a full clone and committed as data. The first version read git log during the build and emitted nothing in production, because Cloudflare shallow-clones and git log returns one grafted commit for every file
• npm run indexnow — submit changed URLs to Bing, Yandex, Seznam and Naver. It prints on every run that Google does not participate, because reading a green result as "submitted to search engines" is how a site goes weeks with nobody asking why Google has not picked something up
• npm run seo (optional) — full-site SEO audit, most useful as a baseline: capture the old site before migrating, then fail only on findings new since. Metadata parity is what a rebuild loses quietly
• Lead retention — a KV expirationTtl from one number in site.ts, because "indefinitely" is not a retention period
• docs/ — runbook (verification matrix, go-live order, first-week watch), content guide, analytics (the rules whose failure looks like success), a traps file seeded with this codebase's silent failures, and handover.md — the one document written for the client rather than a developer, rendered to PDF by npm run handover

npm create website-build-kit@latest my-site

It checks your Node version before writing anything, restores the .gitignore npm strips from published packages, names the project after the directory, and installs. npx degit nurkamol/website-build-kit/template my-site still works if you would rather not run a scaffolder.

Node 22.12+. It builds green with no content, no images and no secrets. Fill in src/data/business.ts first — everything else reads from it. Then npm run tells will tell you what is still undecided.

The two CLAUDE.md files

They do different jobs and neither replaces the skill.

The skill is what teaches the method. These are what stop a future session breaking the conventions once the method has been applied.

Growing it

New prompts, skills and template pieces are meant to accumulate. See docs/adding-to-the-kit.md for the bar, and docs/roadmap.md for what is queued — including what was deliberately rejected, so it does not come back as a new idea.

The bar for adding a trap: it failed silently on a real build. Not "this is good practice" — something that looked fine and was not.

Licence

MIT. Use it, fork it, build client sites with it, sell the result.

Sites built from it carry no obligation. The template/ contents are meant to be copied into client projects, and MIT does not follow them there in any way that matters: no attribution in the finished website, no restriction on the deliverable. A licence on the toolchain that encumbered client work would make the toolchain unusable for the work it exists for.

The one thing worth asking: if the method here is useful, say where it came from. That is a request, not a term.

Provenance

Sharpened on getmiohome.com and expressducttest.com, both WordPress rebuilds onto Astro + Cloudflare Workers. Client names and project detail in this repository are shared in confidence; contact details, credentials and analytics IDs are not permitted here at all — CLAUDE.md carries the sweep that enforces it.