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

1. Use SSG when possible - Pre-render static content
2. Optimize images - Use Astro's <Image /> component
3. Minimize client JS - Use React only where needed
4. Leverage edge caching - Set cache headers on API routes
5. Use KV for caching - Cache expensive operations

Development

1. Type everything - Use TypeScript for better DX
2. Validate content - Use Zod schemas for content collections
3. Test locally - Use platformProxy for bindings in dev
4. Generate types - Run wrangler types after binding changes
5. Follow conventions - Use file-based routing

Deployment

1. Deploy to Workers - Use Workers, not Pages (Cloudflare recommendation)
2. Use environments - staging/production in wrangler.jsonc
3. Automate with CI/CD - GitHub Actions for deployments
4. Monitor performance - Use Cloudflare Analytics
5. 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:

1. Search for latest Astro documentation
2. Update reference files with new patterns
3. Add new scripts for common workflows
4. Test changes with real projects
5. 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