# Astro SSR + Tailwind CSS + Cloudflare — AI Agent Guidelines & Architecture Rules

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

---

## AGENTS.md
```markdown
# Project Architecture & Guidelines (Astro + Tailwind + Cloudflare)

## 1. Core Architecture
- **Framework**: Astro 5 with `@astrojs/cloudflare` server adapter (`output: "server"`).
- **UI Hydration**: React client islands mounted with selective directives (`client:load`, `client:visible`, `client:idle`).
- **Styling**: Tailwind CSS with strict CSS variables and dark-theme tokens.
- **Edge Execution**: Cloudflare Pages Functions / Workers runtime with Cloudflare KV / D1 / Hyperdrive.

## 2. Islands Architecture Rules
- Keep pages and static wrappers in `.astro` components for zero-JS delivery.
- Convert components to React (`.tsx`) ONLY when interactive client-side state is required (modals, dropdowns, filters).
- Pass server-computed data as serializable props into React islands; avoid fetching boilerplate inside client components.

## 3. Cloudflare Edge & Environment Constraints
- Do NOT rely on Node.js core modules (`fs`, `child_process`) at runtime unless supported by Node compatibility flags.
- Access edge bindings (KV, D1, Hyperdrive, Secrets) via `Astro.locals.runtime.env` in Astro pages or `locals` in API routes.
- Enforce SSRF protection and timeout limits (`AbortSignal.timeout`) on all outbound `fetch` calls.

## 4. API Endpoints & Data Flow
- Place server endpoints in `src/pages/api/` exporting HTTP methods (`export const POST: APIRoute`, `export const GET`).
- Always set `export const prerender = false` on dynamic API routes.
- Return explicit `Response` objects with standard `Content-Type: application/json` headers and proper HTTP status codes.

## 5. Coding Standards
- Strict TypeScript (`tsc --noEmit`).
- English-only copy, code comments, and documentation.
- Prettier formatting with 2-space indentation.

## 6. Testing Conventions
- Use Playwright for end-to-end tests covering Astro pages and hydrated React islands (`@astro/test` or a standalone Playwright config).
- Test islands in isolation with Vitest + `@testing-library/react` before wiring them into `.astro` pages.
- Run `tsc --noEmit` as a required pre-merge check; treat type errors as test failures, not warnings.
- Verify edge-only code paths (KV, D1, Hyperdrive) with `wrangler dev --local` or `wrangler dev --remote` against a staging binding before deploying.

## 7. Git Workflow & PR Conventions
- 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`).
- Every PR touching `.astro` pages must include a screenshot or Playwright trace for the changed route.
- Run `bun run build` locally before opening a PR; a failed Cloudflare adapter build blocks merge.
- Squash-merge feature branches; keep `main` deployable to Cloudflare Pages at every commit.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — Astro + Tailwind + Cloudflare Commands & Conventions

## Common Commands
- `bun run dev` - Start local Astro development server with HMR
- `bun run build` - Build server entrypoints and client assets for Cloudflare
- `bun run preview` - Preview production build locally via Wrangler
- `bun run lint` - Run ESLint and type checking (`tsc --noEmit`)

## Code Style Guidelines
- Use `.astro` files for layout, SEO meta tags, and static content.
- Use `.tsx` for interactive client islands.
- Hydrate islands lazily (`client:visible`) unless immediately required in viewport (`client:load`).
- Prefer Tailwind CSS utility classes aligned with design tokens.
- Manage session auth via cookies or Bearer headers.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: Astro SSR + Tailwind CSS + Cloudflare architecture rules
globs: ["**/*.astro", "**/*.tsx", "**/*.ts"]
alwaysApply: true
---

# Astro + Tailwind + Cloudflare

- Astro 5 with `@astrojs/cloudflare` adapter, `output: "server"`.
- Keep pages/wrappers as `.astro` (zero JS). Convert to `.tsx` ONLY for interactive client state.
- Hydrate islands with the narrowest directive that works: `client:visible` > `client:idle` > `client:load`.
- Pass server-computed data as serializable props into islands; never fetch inside a client component when the parent `.astro` already has the data.
- No Node.js core modules (`fs`, `child_process`) unless Node compat flags are explicitly enabled.
- Access edge bindings (KV, D1, Hyperdrive, Secrets) via `Astro.locals.runtime.env` in pages, `locals` in API routes.
- `AbortSignal.timeout()` on every outbound `fetch` — no unbounded requests on the edge.
- API routes live in `src/pages/api/`, export `prerender = false`, return explicit `Response` objects with correct `Content-Type`.
- Tailwind CSS with design-token CSS variables; no ad-hoc hex colors in class names.
- `tsc --noEmit` must pass before commit. Zero `any`.
```

---

## Architecture Overview & Best Practices
## 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.