astro-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro Developer Skill

Astro开发者技能

Context-loading skill for AI agents and developers working in the Astro monorepo. Loads relevant documentation based on your task.

供在Astro monorepo中工作的AI Agent和开发者使用的上下文加载技能，可根据你的任务加载相关文档。

Quick Decision Matrix

快速决策矩阵

What are you doing? → Read these files:

Task	Primary Docs	Supporting Docs
Adding a core feature	architecture.md, constraints.md	testing.md
Fixing a bug	debugging.md	architecture.md
Writing/fixing tests	testing.md	constraints.md
Creating an integration	Explore `packages/integrations/` for examples	testing.md
Understanding architecture	architecture.md	-
Dealing with errors	debugging.md, constraints.md	testing.md
Understanding constraints	constraints.md	architecture.md

你当前要执行什么任务？ → 阅读以下文件：

任务	主要文档	辅助文档
新增核心功能	architecture.md, constraints.md	testing.md
修复bug	debugging.md	architecture.md
编写/修复测试	testing.md	constraints.md
创建集成	查看 `packages/integrations/` 下的示例	testing.md
了解架构	architecture.md	-
处理错误	debugging.md, constraints.md	testing.md
了解约束	constraints.md	architecture.md

Critical Warnings

关键警告

Before you start, be aware of these common pitfalls:

Prefer Unit Tests: Write unit-testable code by default. Use integration tests only when necessary → testing.md
Node.js API Restrictions: Cannot use Node.js APIs in
```
runtime/
```
code → constraints.md
Test Isolation: Must set unique
```
outDir
```
for each integration test → testing.md
Runtime Boundaries: Core vs Vite vs Browser execution contexts → architecture.md
Prerelease Mode: Changesets target
```
origin/next
```
branch (check
```
.changeset/config.json
```
)

开始开发前，请留意这些常见的陷阱：

优先编写单元测试：默认编写可单元测试的代码，仅在必要时使用集成测试 → testing.md
Node.js API使用限制：禁止在
```
runtime/
```
代码中使用Node.js API → constraints.md
测试隔离：每个集成测试必须设置唯一的
```
outDir
```
→ testing.md
运行时边界：核心、Vite、浏览器三种执行上下文的区别 → architecture.md
预发布模式：Changesets目标分支为
```
origin/next
```
（可查看
```
.changeset/config.json
```
确认）

Quick Command Reference

快速命令参考

bash

undefined

bash

undefined

Development

开发相关

pnpm install # Install (root only) pnpm run build # Build all packages pnpm run dev # Watch mode pnpm run lint # Lint codebase

pnpm install # 仅在根目录执行安装 pnpm run build # 构建所有包 pnpm run dev # 监听模式 pnpm run lint # 检查代码规范

Testing

测试相关

pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js" # All tests pnpm -C packages/astro exec astro-scripts test -m "pattern" # Filter tests pnpm run test:e2e # E2E tests node --test test/file.test.js # Single test

pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js" # 运行所有测试 pnpm -C packages/astro exec astro-scripts test -m "pattern" # 按规则过滤测试 pnpm run test:e2e # 运行E2E测试 node --test test/file.test.js # 运行单个测试

Examples

示例相关

pnpm --filter @example/minimal run dev # Run example

pnpm --filter @example/minimal run dev # 运行示例项目

Changesets

Changesets相关

pnpm exec changeset --empty # Create changeset, no interactive mode

undefined

pnpm exec changeset --empty # 非交互模式创建changeset

undefined

Key File Paths

关键文件路径

packages/astro/src/
├── core/              # Node.js execution context (build/dev commands)
├── runtime/
│   ├── server/        # Vite SSR execution context
│   └── client/        # Browser execution context
├── virtual-modules/   # Virtual module entry points
├── content/           # Content layer system
├── vite-plugin-*/     # Vite plugins
└── types/             # Centralized TypeScript types

packages/integrations/  # Official integrations
examples/              # Test your changes here
test/fixtures/         # Test fixtures

Note: Error stack traces in

node_modules/

map to source in

packages/

. See architecture.md for details.

packages/astro/src/
├── core/              # Node.js执行上下文（构建/开发命令）
├── runtime/
│   ├── server/        # Vite SSR执行上下文
│   └── client/        # 浏览器执行上下文
├── virtual-modules/   # 虚拟模块入口
├── content/           # 内容层系统
├── vite-plugin-*/     # Vite插件
└── types/             # 集中式TypeScript类型定义

packages/integrations/  # 官方集成
examples/              # 可在此处测试你的代码变更
test/fixtures/         # 测试用例依赖资源

注意：

node_modules/

中的错误栈对应

packages/

下的源码，详情可查看architecture.md。

Usage

使用方法

This skill loads relevant context—it doesn't orchestrate workflows. After loading appropriate docs:

Read the recommended files for your task
Apply the patterns and constraints described
Use the commands and file paths provided
Search docs for error messages if you encounter issues

本技能仅用于加载相关上下文，不负责编排工作流。加载对应文档后：

阅读推荐的对应任务文档
遵循文档中描述的模式和约束
使用提供的命令和参考文件路径
遇到问题时可在文档中搜索错误信息

Architecture Quick Summary

架构快速概览

Three Execution Contexts:

core/ → Node.js, build/dev commands, avoid Node APIs except in Vite plugins
runtime/server/ → Vite SSR, CANNOT use Node APIs
runtime/client/ → Browser, CANNOT use Node APIs at all

Five Pipeline Types:

RunnablePipeline →
```
astro dev
```
with Vite loader system
NonRunnablePipeline →
```
astro dev
```
without runtime module loading (Cloudflare adapter)
BuildPipeline →
```
astro build
```
+ prerendering
AppPipeline → Production serverless/SSR
ContainerPipeline → Container API

See architecture.md for complete details.

三种执行上下文：

core/ → Node.js环境，负责构建/开发命令，除Vite插件外避免使用Node API
runtime/server/ → Vite SSR环境，禁止使用Node API
runtime/client/ → 浏览器环境，完全禁止使用Node API

五种流水线类型：

RunnablePipeline → 搭载Vite加载系统的
```
astro dev
```
NonRunnablePipeline → 无运行时模块加载的
```
astro dev
```
（Cloudflare适配器）
BuildPipeline →
```
astro build
```
+ 预渲染
AppPipeline → 生产环境无服务器/SSR
ContainerPipeline → 容器API

完整详情可查看architecture.md。

Testing Quick Summary

测试快速概览

Philosophy: Prefer unit tests over integration tests. Write unit-testable code by default.

Unit tests (fast, preferred):

Test pure functions and business logic
Extract business logic from infrastructure
Use dependency injection

Integration tests (slow, use sparingly):

Only for features that cannot be unit tested (virtual modules, full build pipeline)
Always set unique
```
outDir
```
to avoid cache pollution

See testing.md for complete patterns and examples.

设计理念：优先选择单元测试而非集成测试，默认编写可单元测试的代码。

单元测试（速度快，优先使用）：

测试纯函数和业务逻辑
将业务逻辑与基础设施代码解耦
使用依赖注入

集成测试（速度慢，谨慎使用）：

仅用于无法进行单元测试的功能（虚拟模块、完整构建流水线）
始终设置唯一
```
outDir
```
避免缓存污染

完整模式和示例可查看testing.md。

When NOT to Use This Skill

不适用场景

Bug triage: Use the
```
triage
```
skill instead
GitHub Actions analysis: Use the
```
analyze-github-action-logs
```
skill
Simple questions: Just ask directly, don't load this skill

Bug分诊：请使用
```
triage
```
技能
GitHub Actions日志分析：请使用
```
analyze-github-action-logs
```
技能
简单问题咨询：直接提问即可，无需加载本技能