STACK IT FAST
ALL RULES & SKILLS

Astro SSR + Tailwind CSS + Cloudflare

Raw .MD astro-tailwind-cloudflare
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

Architecture rules for Astro server-side rendering, React client islands, Tailwind CSS, and Cloudflare Pages/Workers edge deployment.

AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/astro-tailwind-cloudflare
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
AGENTS.md·39 lines · 2.7 KB
1# Project Architecture & Guidelines (Astro + Tailwind + Cloudflare)
2
3## 1. Core Architecture
4- **Framework**: Astro 5 with `@astrojs/cloudflare` server adapter (`output: "server"`).
5- **UI Hydration**: React client islands mounted with selective directives (`client:load`, `client:visible`, `client:idle`).
6- **Styling**: Tailwind CSS with strict CSS variables and dark-theme tokens.
7- **Edge Execution**: Cloudflare Pages Functions / Workers runtime with Cloudflare KV / D1 / Hyperdrive.
8
9## 2. Islands Architecture Rules
10- Keep pages and static wrappers in `.astro` components for zero-JS delivery.
11- Convert components to React (`.tsx`) ONLY when interactive client-side state is required (modals, dropdowns, filters).
12- Pass server-computed data as serializable props into React islands; avoid fetching boilerplate inside client components.
13
14## 3. Cloudflare Edge & Environment Constraints
15- Do NOT rely on Node.js core modules (`fs`, `child_process`) at runtime unless supported by Node compatibility flags.
16- Access edge bindings (KV, D1, Hyperdrive, Secrets) via `Astro.locals.runtime.env` in Astro pages or `locals` in API routes.
17- Enforce SSRF protection and timeout limits (`AbortSignal.timeout`) on all outbound `fetch` calls.
18
19## 4. API Endpoints & Data Flow
20- Place server endpoints in `src/pages/api/` exporting HTTP methods (`export const POST: APIRoute`, `export const GET`).
21- Always set `export const prerender = false` on dynamic API routes.
22- Return explicit `Response` objects with standard `Content-Type: application/json` headers and proper HTTP status codes.
23
24## 5. Coding Standards
25- Strict TypeScript (`tsc --noEmit`).
26- English-only copy, code comments, and documentation.
27- Prettier formatting with 2-space indentation.
28
29## 6. Testing Conventions
30- Use Playwright for end-to-end tests covering Astro pages and hydrated React islands (`@astro/test` or a standalone Playwright config).
31- Test islands in isolation with Vitest + `@testing-library/react` before wiring them into `.astro` pages.
32- Run `tsc --noEmit` as a required pre-merge check; treat type errors as test failures, not warnings.
33- Verify edge-only code paths (KV, D1, Hyperdrive) with `wrangler dev --local` or `wrangler dev --remote` against a staging binding before deploying.
34
35## 7. Git Workflow & PR Conventions
36- Commit messages follow Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`) scoped to the touched package when in a monorepo (e.g. `feat(web): add pricing page`).
37- Every PR touching `.astro` pages must include a screenshot or Playwright trace for the changed route.
38- Run `bun run build` locally before opening a PR; a failed Cloudflare adapter build blocks merge.
39- Squash-merge feature branches; keep `main` deployable to Cloudflare Pages at every commit.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

Architecture Overview

Standardized production guidelines for Astro SSR, React Client Islands, Tailwind CSS, and Cloudflare Edge Deployment.

Key Advantages

  • Sub-100ms Global TTFB: Cloudflare edge distribution ensures instant response times worldwide.
  • Zero Client-Side JS by Default: Astro ships zero JavaScript unless explicitly hydrated with React islands.
  • Cost Efficiency: Serverless edge execution eliminates always-on server costs.
FREQUENTLY ASKED QUESTIONS

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

Yes. AGENTS.md is the open cross-tool standard read natively by Cursor, Claude Code, Windsurf, GitHub Copilot, and 30+ other agents. This page also ships a dedicated .mdc file for Cursor's modern .cursor/rules format if you prefer scoped, glob-based rule loading.

Why must Astro islands avoid fetching data with useEffect?

Astro server-renders .astro pages before any client JavaScript runs, so data is already available at render time. Fetching again inside a React island with useEffect duplicates the request, adds a loading flash, and defeats the zero-JS-by-default model — pass the data down as a serializable prop instead.

Can I use Node.js APIs in a Cloudflare Pages Function?

Only with the Node compatibility flag enabled in wrangler.toml (nodejs_compat). Without it, fs, child_process, and other Node core modules are unavailable at the edge — use Web Platform APIs (fetch, crypto, Request/Response) instead, which work identically in Cloudflare Workers.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills