Astro: rules before pages, then publishing
The full process, private repository included: design system first, then implementation, then automatic deployment on every push. With the five traps that cost me time because none of them is in the documentation.
Two tools, two stages. Claude Design is used to set the rules: colour and spacing tokens, surfaces, what the brand rules out. Claude Code is used to apply them. Keeping the two apart makes it possible later to judge a page against a written rule.
The system comes as CSS variables and a rules file. The second is the more useful, because it lists what is forbidden: no hard-coded hex values, no drop shadows, no border radius. A checking script reads the whole repository and fails the build on any deviation. It has already rejected code I wrote myself, which shows that it works.
// package.json — the repository's front door
{
"scripts": {
"check": "astro check",
"adherence": "node scripts/check-adherence.mjs",
"verify": "npm run check && npm run adherence && npm run build"
}
}In static mode, Astro produces only HTML, CSS and a few kilobytes of script. There is no server rendering, so nothing to keep running in production: the page served is the page that was built. That is what makes hosting almost free and allows someone else to take the site over.
The repository is private, the site public. GitHub Actions builds the site, then uploads the output folder to Cloudflare Pages. Two secrets are enough: an API token and the account ID. Deployment depends on the check, and nothing is published if a system rule is broken.
- name: Verify
run: npm run verify
working-directory: site
- name: Publish to Cloudflare Pages
if: github.event_name != 'pull_request'
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
workingDirectory: site
command: pages deploy dist --project-name=preview-commutator --branch=main- You cannot add the Git integration to an existing Pages project. A project created for direct upload stays that way: either recreate it or drive it from Actions, as this site does.
- The wrangler action splits the command on spaces. An option containing a multi-line message breaks it, and the error message does not help. The command has to fit on a single line of simple arguments.
- Cloudflare adds a suffix to the project subdomain, so the name you choose does not give the address you expect. Read the actual address instead of guessing it.
- A custom domain is not configured in DNS alone. Until it is attached to the project in Cloudflare, resolution works but the certificate fails, which sends you looking for the cause in the wrong place.
- The edge cache keeps pages for a long time. A renamed page was still being served a week after it was deleted, with a one-week cache-control and a HIT status. Deleting a route does not clear that cache; an explicit redirect is needed.
# public/_redirects — old addresses go straight to the final destination,
# not chained one into the next
/journal/* /points-de-vue/:splat 301
/journal /points-de-vue 301Only the domain name. The free Pages plan is more than enough for a site this size, and GitHub Actions does not charge for public repositories or small volumes. The main investment lies elsewhere: the rules written at the start take a day and save weeks of rework.