astro-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro Development Skill

Astro开发技能

Overview

概述

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

本指南全面介绍如何使用Astro、React、Tailwind CSS v4构建现代Web应用，并部署到Cloudflare Workers。

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

项目初始化 - 遵循最佳实践快速搭建新的Astro项目
内容集合设置 - 生成类型安全的内容Schema
视图过渡集成 - 自动添加流畅的页面过渡效果

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

Cloudflare Workers - 优先基于Workers部署（而非Pages）
Cloudflare D1 - 无服务器SQLite数据库集成
React集成 - 交互式孤岛与水化策略
Tailwind CSS v4 - 无需配置文件的CSS优先配置
内容集合 - 类型安全的内容管理
视图过渡 - 流畅的页面动画
GitHub Actions - CI/CD自动化

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

BaseLayout - 包含页眉、页脚和视图过渡的完整页面布局
Card - 采用Tailwind样式的可复用卡片组件
Button - 包含多种变体和尺寸的React按钮

Quick Start

快速开始

Initialize New Project

初始化新项目

For Cloudflare Workers deployment (recommended):

bash

./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:

bash

./scripts/init_astro_standard.sh my-site

推荐：部署到Cloudflare Workers时使用

bash

./scripts/init_astro_cloudflare.sh my-app

创建以下内容：

带SSR的Astro项目
React集成
Tailwind CSS v4
已配置的Cloudflare适配器
用于Workers部署的wrangler.jsonc

标准静态站点：

bash

./scripts/init_astro_standard.sh my-site

Add Content Collections

添加内容集合

bash

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)

bash

python scripts/setup_content_collection.py blog

创建以下内容：

```
src/content/blog/
```
目录
```
src/content/config.ts
```
中的类型安全Zod Schema
示例博客文章

支持的集合类型：

```
blog
```
- 带前置元数据的博客文章
```
docs
```
- 文档页面
```
products
```
- 产品数据（JSON格式）

Add View Transitions

添加视图过渡

bash

python scripts/add_view_transitions.py

Automatically adds View Transitions API to all layouts in

src/layouts/

bash

python scripts/add_view_transitions.py

自动为

src/layouts/

中的所有布局添加视图过渡API。

Common Workflows

常见工作流

1. Create Astro + Cloudflare Workers Site

1. 创建Astro + Cloudflare Workers站点

bash

undefined

bash

undefined

Initialize project

初始化项目

./scripts/init_astro_cloudflare.sh my-blog

cd my-blog

./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

部署到Cloudflare Workers

npx wrangler deploy

undefined

npx wrangler deploy

undefined

2. Add D1 Database

2. 添加D1数据库

See

references/cloudflare-d1.md

for:

Database creation
Schema definition
Query patterns
Drizzle ORM integration

请查看

references/cloudflare-d1.md

了解：

数据库创建
Schema定义
查询模式
Drizzle ORM集成

3. Build Interactive Components

3. 构建交互式组件

See

references/react-integration.md

for:

Client directives (load, idle, visible)
Hooks and state management
Form handling
Context API

请查看

references/react-integration.md

了解：

客户端指令（load、idle、visible）
Hooks与状态管理
表单处理
Context API

4. Style with Tailwind v4

4. 使用Tailwind v4设置样式

See

references/tailwind-setup.md

for:

CSS-first configuration
Custom themes
Dark mode
OKLCH colors
Container queries

请查看

references/tailwind-setup.md

了解：

CSS优先配置
自定义主题
深色模式
OKLCH颜色
容器查询

Deployment

部署

Cloudflare Workers (Recommended)

Cloudflare Workers（推荐）

bash

undefined

bash

undefined

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

npm run build npx wrangler deploy


**核心要点：**
- 使用`wrangler.jsonc`配置
- 部署到Cloudflare Workers（而非Pages）
- 主入口文件：`./dist/_worker.js`
- 静态资源从`./dist`提供

请查看`references/cloudflare-workers.md`了解：
- 绑定（KV、D1、R2）
- 环境变量
- TypeScript类型
- SSR配置

GitHub Actions

See

references/github-actions.md

for:

Automated deployments
Preview deployments for PRs
Security scanning
Performance budgets

请查看

references/github-actions.md

了解：

自动化部署
PR预览部署
安全扫描
性能预算

Key Concepts

核心概念

Rendering Modes

渲染模式

javascript

// 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',
});

javascript

// astro.config.mjs

// 服务器端渲染（所有页面按需渲染）
export default defineConfig({
  output: 'server',
});

// 混合模式（默认静态渲染，可选择SSR）
export default defineConfig({
  output: 'hybrid',
});

// 静态模式（构建时预渲染）
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

my-astro-app/
├── src/
│   ├── pages/              # 基于文件的路由
│   │   ├── index.astro
│   │   ├── blog/
│   │   │   └── [...slug].astro
│   │   └── api/           # API端点
│   │       └── data.ts
│   ├── layouts/           # 页面布局
│   │   └── BaseLayout.astro
│   ├── components/        # Astro组件
│   │   └── Card.astro
│   ├── components/        # React组件
│   │   └── Button.tsx
│   ├── content/           # 内容集合
│   │   ├── config.ts
│   │   └── blog/
│   ├── styles/            # 全局CSS
│   │   └── global.css
│   └── env.d.ts           # TypeScript类型定义
├── public/                # 静态资源
│   └── .assetsignore      # Workers资源配置
├── astro.config.mjs       # Astro配置
├── wrangler.jsonc         # Cloudflare Workers配置
├── package.json
└── tsconfig.json

Client Directives

客户端指令

Control when React components hydrate:

astro

<!-- 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" />

控制React组件的水化时机：

astro

<!-- 立即水化 -->
<Counter client:load />

<!-- 空闲时水化 -->
<SocialShare client:idle />

<!-- 可见时水化 -->
<Comments client:visible />

<!-- 满足特定媒体查询时水化 -->
<MobileMenu client:media="(max-width: 768px)" />

<!-- 仅客户端渲染（无SSR） -->
<BrowserWidget client:only="react" />

Cloudflare Runtime

Cloudflare运行时

Access Workers APIs in pages and API routes:

astro

---
// 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;
---

在页面和API路由中访问Workers API：

astro

---
// 在.astro文件中
const { env, cf, ctx } = Astro.locals.runtime;

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

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

// 请求属性
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

尽可能使用SSG - 预渲染静态内容
优化图片 - 使用Astro的
```
<Image />
```
组件
最小化客户端JS - 仅在必要时使用React
利用边缘缓存 - 为API路由设置缓存头
使用KV缓存 - 缓存高开销操作

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

全类型化 - 使用TypeScript提升开发体验
验证内容 - 为内容集合使用Zod Schema
本地测试 - 开发时使用
```
platformProxy
```
模拟绑定
生成类型 - 修改绑定后运行
```
wrangler types
```
遵循约定 - 使用基于文件的路由

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

部署到Workers - 优先使用Workers而非Pages（Cloudflare官方推荐）
使用多环境 - 在wrangler.jsonc中配置 staging/生产环境
用CI/CD自动化 - 使用GitHub Actions实现部署自动化
监控性能 - 使用Cloudflare分析工具
查看日志 - 使用
```
wrangler tail
```
调试

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

构建错误：

运行
```
npx astro check
```
排查TypeScript错误
检查Node.js版本（需18+）
清除
```
.astro
```
缓存后重新构建

水化问题：

确保React组件添加了
```
client:*
```
指令
检查是否存在与SSR不兼容的代码（如浏览器API）
若组件无法服务端渲染，使用
```
client:only
```

部署问题：

验证
```
wrangler.jsonc
```
配置
检查
```
CLOUDFLARE_API_TOKEN
```
权限
确保绑定配置正确
查看
```
wrangler tail
```
日志

Tailwind不生效：

在布局中引入
```
global.css
```
验证
```
astro.config.mjs
```
中的Vite插件配置
确保CSS文件顶部包含
```
@import "tailwindcss"
```

Resources

资源

Documentation

文档

Tools

工具

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

```
cloudflare-workers.md
```
- Workers部署指南
```
cloudflare-d1.md
```
- D1数据库设置
```
react-integration.md
```
- React使用模式
```
tailwind-setup.md
```
- Tailwind v4配置
```
content-collections.md
```
- 内容管理
```
view-transitions.md
```
- 页面动画
```
github-actions.md
```
- CI/CD工作流

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

Astro及其生态系统发展迅速，更新本技能请遵循以下步骤：

查阅最新的Astro文档
更新参考文件中的新用法
为常见工作流添加新脚本
在实际项目中测试变更
重新打包技能

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

本技能基于以下版本：

Astro 5.x
React 19.x
Tailwind CSS 4.x
Cloudflare Workers（最新版）
@astrojs/cloudflare 11.x+

最后更新：2024年10月

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

优先Cloudflare Workers，而非Pages - 本技能仅聚焦于Workers部署
Tailwind v4 - 使用CSS优先配置（无tailwind.config.js）
类型安全 - 全程使用TypeScript
现代技术栈 - 采用最新版本与最佳实践