---
name: astro-tailwind-cloudflare
description: "Use when building, refactoring, or reviewing a Astro SSR + Tailwind CSS + Cloudflare project (Astro, Tailwind CSS, Cloudflare, TypeScript, React). Architecture rules for Astro server-side rendering, React client islands, Tailwind CSS, and Cloudflare Pages/Workers edge deployment."
license: MIT
metadata:
  source: https://stackitfast.com/rules/astro-tailwind-cloudflare
  version: "2026-10-04"
---

# Astro SSR + Tailwind CSS + Cloudflare — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Astro SSR + Tailwind CSS + Cloudflare codebase.
- Whenever the project depends on Astro, Tailwind CSS, Cloudflare, TypeScript, React.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (Astro + Tailwind + Cloudflare)

## 1. Core Architecture
- **Framework**: Astro 7 with `@astrojs/cloudflare` server adapter (`output: "server"`); Node 22.12+ for builds, and only Content Layer collections (`src/content.config.ts`).
- **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.

## Source
Maintained at https://stackitfast.com/rules/astro-tailwind-cloudflare — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.