Astro Development Skill

Overview

Comprehensive guide for building modern web applications with Astro, React, Tailwind CSS v4, and Cloudflare Workers deployment.

What This Skill Provides

Automation Scripts

• Project initialization - Bootstrap new Astro projects with best practices

• Content collections setup - Generate type-safe content schemas

• View Transitions integration - Add smooth page transitions automatically

Reference Documentation

• Cloudflare Workers - Workers-first deployment (NOT Pages)

• Cloudflare D1 - Serverless SQLite database integration

• React integration - Interactive islands and hydration strategies

• Tailwind CSS v4 - CSS-first configuration without config files

• Content Collections - Type-safe content management

• View Transitions - Smooth page animations

• GitHub Actions - CI/CD automation

Component Templates

• BaseLayout - Full page layout with header, footer, and View Transitions

• Card - Reusable card component with Tailwind styling

• Button - React button with variants and sizes

Quick Start

Initialize New Project

For Cloudflare Workers deployment (recommended):

./scripts/init_astro_cloudflare.sh my-app

Creates:

• Astro project with SSR

• React integration

• Tailwind CSS v4

• Cloudflare adapter configured

• wrangler.jsonc for Workers deployment

For standard static site:

./scripts/init_astro_standard.sh my-site

Add Content Collections

python scripts/setup_content_collection.py blog

Creates:

• src/content/blog/ directory

• Type-safe Zod schema in src/content/config.ts

• Example blog post

Collection types:

• blog

• Blog posts with frontmatter

• docs

• Documentation pages

• products

• Product data (JSON)

Add View Transitions

python scripts/add_view_transitions.py

Automatically adds View Transitions API to all layouts in src/layouts/ .

Common Workflows

1. Create Astro + Cloudflare Workers Site

Initialize project

./scripts/init_astro_cloudflare.sh my-blog

cd my-blog

Set up content collections

python ../scripts/setup_content_collection.py blog

Add View Transitions

python ../scripts/add_view_transitions.py

Start development

npm run dev

Deploy to Cloudflare Workers

npx wrangler deploy

2. Add D1 Database

See references/cloudflare-d1.md for:

• Database creation

• Schema definition

• Query patterns

• Drizzle ORM integration

3. Build Interactive Components

See references/react-integration.md for:

• Client directives (load, idle, visible)

• Hooks and state management

• Form handling

• Context API

4. Style with Tailwind v4

See references/tailwind-setup.md for:

• CSS-first configuration

• Custom themes

• Dark mode

• OKLCH colors

• Container queries

Deployment

Cloudflare Workers (Recommended)

One-time setup

npm install -g wrangler wrangler login

Deploy

npm run build npx wrangler deploy

Key points:

• Uses wrangler.jsonc configuration

• Deploys to Cloudflare Workers (NOT Pages)

• Main entry: ./dist/_worker.js

• Static assets served from ./dist

See references/cloudflare-workers.md for:

• Bindings (KV, D1, R2)

• Environment variables

• TypeScript types

• SSR configuration

GitHub Actions

See references/github-actions.md for:

• Automated deployments

• Preview deployments for PRs

• Security scanning

• Performance budgets

Key Concepts

Rendering Modes

// astro.config.mjs

// Server-Side Rendering (all pages on-demand) export default defineConfig({ output: 'server', });

// Hybrid (static by default, opt-in to SSR) export default defineConfig({ output: 'hybrid', });

// Static (pre-rendered at build time) export default defineConfig({ output: 'static', });

File Structure

my-astro-app/ ├── src/ │ ├── pages/ # File-based routing │ │ ├── index.astro │ │ ├── blog/ │ │ │ └── [...slug].astro │ │ └── api/ # API endpoints │ │ └── data.ts │ ├── layouts/ # Page layouts │ │ └── BaseLayout.astro │ ├── components/ # Astro components │ │ └── Card.astro │ ├── components/ # React components │ │ └── Button.tsx │ ├── content/ # Content collections │ │ ├── config.ts │ │ └── blog/ │ ├── styles/ # Global CSS │ │ └── global.css │ └── env.d.ts # TypeScript types ├── public/ # Static assets │ └── .assetsignore # Workers asset config ├── astro.config.mjs # Astro configuration ├── wrangler.jsonc # Cloudflare Workers config ├── package.json └── tsconfig.json

Client Directives

Control when React components hydrate:

<!-- Hydrate immediately --> <Counter client:load />

<!-- Hydrate when idle --> <SocialShare client:idle />

<!-- Hydrate when visible --> <Comments client:visible />

<!-- Hydrate on specific media query --> <MobileMenu client:media="(max-width: 768px)" />

<!-- Client-only (no SSR) --> <BrowserWidget client:only="react" />

Cloudflare Runtime

Access Workers APIs in pages and API routes:

// In .astro files const { env, cf, ctx } = Astro.locals.runtime;

// Use KV const data = await env.MY_KV.get('key');

// Use D1 const { results } = await env.DB.prepare('SELECT * FROM users').all();

// Request properties const country = cf.country;

Best Practices

Performance

• Use SSG when possible - Pre-render static content

• Optimize images - Use Astro's <Image /> component

• Minimize client JS - Use React only where needed

• Leverage edge caching - Set cache headers on API routes

• Use KV for caching - Cache expensive operations

Development

• Type everything - Use TypeScript for better DX

• Validate content - Use Zod schemas for content collections

• Test locally - Use platformProxy for bindings in dev

• Generate types - Run wrangler types after binding changes

• Follow conventions - Use file-based routing

Deployment

• Deploy to Workers - Use Workers, not Pages (Cloudflare recommendation)

• Use environments - staging/production in wrangler.jsonc

• Automate with CI/CD - GitHub Actions for deployments

• Monitor performance - Use Cloudflare Analytics

• Review logs - Use wrangler tail for debugging

Troubleshooting

Common Issues

Build Errors:

• Run npx astro check for TypeScript errors

• Check Node.js version (18+)

• Clear .astro cache and rebuild

Hydration Issues:

• Ensure React components have client:* directive

• Check for SSR-incompatible code (browser APIs)

• Use client:only if component can't be server-rendered

Deployment Issues:

• Verify wrangler.jsonc configuration

• Check CLOUDFLARE_API_TOKEN permissions

• Ensure bindings are configured correctly

• Review wrangler tail logs

Tailwind Not Working:

• Import global.css in layout

• Verify Vite plugin in astro.config.mjs

• Check @import "tailwindcss" at top of CSS

Resources

Documentation

• Astro Docs

• Cloudflare Workers Docs

• Tailwind CSS v4

• React Docs

Tools

• Astro VS Code Extension

• Wrangler CLI

• Drizzle Studio

Reference Files

• cloudflare-workers.md

• Workers deployment guide

• cloudflare-d1.md

• D1 database setup

• react-integration.md

• React patterns

• tailwind-setup.md

• Tailwind v4 config

• content-collections.md

• Content management

• view-transitions.md

• Page animations

• github-actions.md

• CI/CD workflows

Updating This Skill

Astro and its ecosystem evolve rapidly. To update:

• Search for latest Astro documentation

• Update reference files with new patterns

• Add new scripts for common workflows

• Test changes with real projects

• Repackage the skill

Version Information

This skill is current as of:

• Astro 5.x

• React 19.x

• Tailwind CSS 4.x

• Cloudflare Workers (latest)

• @astrojs/cloudflare 11.x+

Last updated: October 2024

Notes

• Cloudflare Workers, NOT Pages - This skill focuses exclusively on Workers deployment

• Tailwind v4 - Uses CSS-first configuration (no tailwind.config.js)

• Type-safe - Leverages TypeScript throughout

• Modern stack - Latest versions and best practices