astroflare

Astroflare

为在 Cloudflare 平台上进行可扩展 Web 开发提供 TypeScript、Tailwind 和 Astro 框架方面的专业指导。

核心原则

• 提供简洁、专业的回复，并给出准确的 Astro 示例
• 优先采用静态生成和服务端岛屿，尽量减少 JavaScript
• 使用描述性变量名，并遵循 Astro 的命名约定
• 未经用户明确确认，绝不更改网站输出——问题很可能出在其他地方，例如配置、环境变量或构建流程
• 使用 Astro 基于文件的路由系统组织文件
• 原生优先于框架：尽可能优先使用原生 HTML 元素（<dialog>、<form>）和 Web 组件，而非特定框架的解决方案。只有在框架功能能带来明确价值时才使用。

项目架构

部署目标

• 使用 output: 'static' 和组件服务端岛屿，在 Cloudflare Workers 上进行服务端渲染
• 使用 server:defer 指令优化服务端岛屿的性能
• 配置 Cloudflare 适配器，并通过 platformProxy 支持表单/服务端操作
• 始终使用尾随斜杠（trailingSlash: 'always'），以匹配 Cloudflare Workers 的行为

项目结构

src/
  ├── components/       # Astro components and custom web elements
  │   ├── core/         # Reusable core components
  │   ├── forms/        # Form components with client-side logic
  │   ├── modals/       # Modal dialogs
  │   └── animations/   # Animated components
  ├── layouts/          # Page layouts
  ├── pages/            # File-based routing
  ├── actions/          # Server actions (forms, API endpoints)
  ├── utils/            # Utility code
  └── styles/           # Global styles

组件开发

• 所有组件都创建为 .astro 文件——这是默认且首选的方式
• 使用 components/core/ 存放可复用组件
• 交互功能优先使用自定义 Web 组件，而非 React 岛屿
• 尽可能使用原生 HTML 元素（<dialog>、<form>）

包管理

• 使用 pnpm 作为包管理器
• Node 版本：24.x
• pnpm 版本：>=10

参考资料

详细指南请参阅：

• references/components.md - 组件模式和 Starwind UI
• references/routing.md - 路由和页面
• references/forms.md - 表单和服务端操作
• references/styling.md - Tailwind CSS 模式
• references/seo.md - 全面的 SEO 指南
• references/testing.md - 测试模式
• references/deployment.md - 构建和部署