Skip to content
STACK IT FAST
Share

Astro Static Site + Content Collections + Tailwind

Curated rule Content & Directory · Developer Tool & API Updated Oct 2026 Which file does my tool read?
astro-static-content.md

Rules for a fully static Astro 7 site: content collections with Zod schemas, zero-JS pages with rare islands, build-time sitemap and OG images, and static hosting on Cloudflare.

Astro Tailwind CSS TypeScript MDX Cloudflare
Formats
4 files
AGENTS.md
44 lines
CLAUDE.md
14 lines
Languages
TypeScript
Updated
Oct 2026
Used by
4 projects
Install

Writes .claude/skills/astro-static-content/SKILL.md

$ curl -s --create-dirs -o .claude/skills/astro-static-content/SKILL.md https://stackitfast.com/rules/astro-static-content/SKILL.md

Rule files

AGENTS.md· 44 lines · 3.3 KB
1# Project Architecture & Guidelines (Astro Static + Content Collections)
2
3## 1. System Architecture
4- **Framework**: Astro 7 with `output: 'static'` (the default). No server adapter; every route is HTML at build time.
5- **Content**: Content collections defined in `src/content.config.ts` with the `glob()` and `file()` loaders and a Zod schema per collection.
6- **Styling**: Tailwind CSS with a small token set in the config; no runtime CSS-in-JS.
7- **Interactivity**: Astro components by default. A React, Svelte or Vue island only where state must survive after load, hydrated with `client:visible` or `client:idle`, never `client:load` by habit.
8- **Hosting**: Static files on Cloudflare (Workers static assets or Pages). No functions unless a form or API genuinely needs one.
9- **Runtime**: Node 22.12+ for the build (Astro 6 dropped Node 18 and 20).
10
11## 2. File Layout
12- `src/content.config.ts`: Every collection, its loader and its schema in one file.
13- `src/content/<collection>/`: Markdown or MDX entries; file name is the slug.
14- `src/pages/`: File-based routes. Dynamic routes export `getStaticPaths()` built from `getCollection()`.
15- `src/layouts/Base.astro`: The only place that writes `<head>`: title, description, canonical, Open Graph, JSON-LD.
16- `src/components/`: `.astro` components; islands live in `src/components/islands/` so they are easy to count.
17- `src/pages/sitemap.xml.ts`, `rss.xml.ts`, `og/[...slug].png.ts`: Build-time endpoints, prerendered like pages.
18
19## 3. Content Rules
20- Every frontmatter field is in the collection schema. Adding a field means changing the schema first; the build fails on missing or mistyped fields.
21- Use `z.coerce.date()` for dates and `reference()` for links between collections instead of raw slugs.
22- Query with `getCollection()` / `getEntry()` and render with `render(entry)`. The legacy `getEntryBySlug()` API was removed in Astro 6.
23- Drafts use a `draft: z.boolean().default(false)` field filtered out in one helper, not in every page.
24
25## 4. SEO & Performance
26- One layout owns all meta tags; pages pass `title`, `description` and `image` props, never raw `<meta>`.
27- Canonical URLs match the served URLs exactly (pick a trailing-slash policy in `astro.config.mjs` and the host, and keep them aligned).
28- Generate the sitemap, RSS feed and OG images at build time. Nothing about a static page should be computed per request.
29- Use `astro:assets` `<Image />` for local images so width, height and modern formats are emitted at build.
30
31## 5. Coding Standards
32- Strict TypeScript (`astro/tsconfigs/strict`), zero `any`.
33- Keep logic out of `.astro` templates: data shaping goes in `src/lib/*.ts`, which can be unit tested.
34- No client-side router, no global state library, no CMS until the content outgrows a folder of Markdown.
35
36## 6. Testing Conventions
37- `astro check` and `astro build` are the test suite for content: both must pass in CI.
38- Unit test `src/lib/` helpers (slugs, dates, sorting) with Vitest.
39- Add a build-time assertion for the invariants that matter, e.g. every indexable page has a canonical URL and a description under 160 characters.
40
41## 7. Git Workflow & PR Conventions
42- Conventional Commits scoped to the area: `feat(blog): add series field`, `fix(seo): canonical for paginated lists`.
43- A schema change and the content edits it requires land in the same PR.
44- Preview deploys per PR; review the rendered page, not only the Markdown diff.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Guidelines for a fully static Astro 7 site: Markdown and MDX in content collections with Zod schemas, Tailwind CSS, and the occasional island, deployed as plain files to Cloudflare.

Key Advantages

  • Nothing to run after deploy: a static build either succeeds or fails, so there is no runtime state for an agent to debug in production.
  • Schemas on content: every frontmatter field is typed, so “add a field to every post” is a change the type checker verifies.
  • SEO done once: one layout owns the head, and the sitemap, feed and social images are generated with the pages.

Frequently asked questions

When should a static Astro site move to server output?

When a page has to change per request: logged-in views, personalised prices, search over data that is not in the repo. Until then, server output only adds a runtime the agent has to reason about. Moving later is a config change plus an adapter, and individual routes can stay prerendered.

Why content collections instead of a headless CMS?

A collection is a folder of files with a schema the type checker enforces, which is the cheapest possible feedback loop for an agent: a wrong field fails the build. A CMS moves content out of the repo, so the agent can no longer read or verify it in the same change.

Does this AGENTS.md work with Cursor, Claude Code and Windsurf?

Yes. AGENTS.md is the cross-tool standard read by Cursor, Claude Code, Windsurf, Codex and others. A .mdc file is included for Cursor's native rules format.

Used in production

Explore all stacks

elekcsv

5
Headless CSV Ingestion Engine · Solo

Keeping parsing, compiled-validator generation, fuzzy column mapping and bitmap error tracking in one dependency-free core package lets every UI framework reuse identical import logic instead of six separate implementations.

OpenSEO

Open-Source SEO Research Platform · 2-5 people

Running on Cloudflare Workers with D1, Workflows and Durable Objects makes it free-tier friendly to self-host and to scale when hosted. Supporting both D1 and Postgres through Drizzle, plus a Docker path, keeps the project portable beyond Cloudflare.

Tinycast

Native macOS Launcher & Clipboard Manager · Solo / 2-5 people

Staying native with zero third-party dependencies and delegating search to Spotlight and system services keeps memory use low. A small embedded JavaScriptCore runtime adds Raycast extension compatibility without pulling in Electron.

Astro

Island Architecture Web Framework · 1M+ MAU

Vite as a first-class dependency and per-framework, per-host integration packages let Astro ship a fast static-first build while opting into server rendering or client hydration only where a project actually needs it.
Where this stack fits

Stack It First recommends it at:

Web · MVP · SEO-driven
Walk the web roadmap
Every stack ships as files

More AI agent coding rules and skills

View all
astro-tailwind-cloudflare/AGENTS.mdAstro SSR + Tailwind CSS + CloudflareAstro · Tailwind CSS · Cloudflarebun-hono-sqlite/AGENTS.mdBun + Hono + SQLite (libSQL & Drizzle ORM)Bun · Hono · SQLitefastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQLgo-postgres-react/AGENTS.mdGo + PostgreSQL (pgx & sqlc) + ReactGo · PostgreSQL · React