astro-developer Skill

1---2name: astro-developer3description: Comprehensive guide for developing in the Astro monorepo. Covers architecture, debugging, testing, and critical constraints. Use when working on features, fixes, tests, or understanding the codebase structure.4---5 6# Astro Developer Skill7 8Context-loading skill for AI agents and developers working in the Astro monorepo. Loads relevant documentation based on your task.9 10## Quick Decision Matrix11 12**What are you doing?** → **Read these files:**13 14| Task                       | Primary Docs                                                         | Supporting Docs                    |15| -------------------------- | -------------------------------------------------------------------- | ---------------------------------- |16| Adding a core feature      | [architecture.md](architecture.md), [constraints.md](constraints.md) | [testing.md](testing.md)           |17| Fixing a bug               | [debugging.md](debugging.md)                                         | [architecture.md](architecture.md) |18| Writing/fixing tests       | [testing.md](testing.md)                                             | [constraints.md](constraints.md)   |19| Creating an integration    | Explore `packages/integrations/` for examples                        | [testing.md](testing.md)           |20| Understanding architecture | [architecture.md](architecture.md)                                   | -                                  |21| Dealing with errors        | [debugging.md](debugging.md), [constraints.md](constraints.md)       | [testing.md](testing.md)           |22| Understanding constraints  | [constraints.md](constraints.md)                                     | [architecture.md](architecture.md) |23 24## Critical Warnings25 26**Before you start, be aware of these common pitfalls:**27 281. **Prefer Unit Tests**: Write unit-testable code by default. Use integration tests only when necessary → [testing.md](testing.md)292. **Node.js API Restrictions**: Cannot use Node.js APIs in `runtime/` code → [constraints.md](constraints.md)303. **Test Isolation**: Must set unique `outDir` for each integration test → [testing.md](testing.md)314. **Runtime Boundaries**: Core vs Vite vs Browser execution contexts → [architecture.md](architecture.md)325. **Prerelease Mode**: Changesets target `origin/next` branch (check `.changeset/config.json`)33 34## Quick Command Reference35 36```bash37# Development38pnpm install                                    # Install (root only)39pnpm run build                                  # Build all packages40pnpm run dev                                    # Watch mode41pnpm run lint                                   # Lint codebase42 43# Testing44pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js"  # All tests45pnpm -C packages/astro exec astro-scripts test -m "pattern"         # Filter tests46pnpm run test:e2e                               # E2E tests47node --test test/file.test.js                   # Single test48 49# Examples50pnpm --filter @example/minimal run dev          # Run example51 52# Changesets53pnpm exec changeset --empty                     # Create changeset, no interactive mode54```55 56## Key File Paths57 58```59packages/astro/src/60├── core/              # Node.js execution context (build/dev commands)61├── runtime/62│   ├── server/        # Vite SSR execution context63│   └── client/        # Browser execution context64├── virtual-modules/   # Virtual module entry points65├── content/           # Content layer system66├── vite-plugin-*/     # Vite plugins67└── types/             # Centralized TypeScript types68 69packages/integrations/  # Official integrations70examples/              # Test your changes here71test/fixtures/         # Test fixtures72```73 74**Note**: Error stack traces in `node_modules/` map to source in `packages/`. See [architecture.md](architecture.md) for details.75 76## Usage77 78This skill loads relevant context—it doesn't orchestrate workflows. After loading appropriate docs:79 801. Read the recommended files for your task812. Apply the patterns and constraints described823. Use the commands and file paths provided834. Search docs for error messages if you encounter issues84 85## Architecture Quick Summary86 87**Three Execution Contexts:**88 89- **core/** → Node.js, build/dev commands, avoid Node APIs except in Vite plugins90- **runtime/server/** → Vite SSR, CANNOT use Node APIs91- **runtime/client/** → Browser, CANNOT use Node APIs at all92 93**Five Pipeline Types:**94 95- **RunnablePipeline** → `astro dev` with Vite loader system96- **NonRunnablePipeline** → `astro dev` without runtime module loading (Cloudflare adapter)97- **BuildPipeline** → `astro build` + prerendering98- **AppPipeline** → Production serverless/SSR99- **ContainerPipeline** → Container API100 101See [architecture.md](architecture.md) for complete details.102 103## Testing Quick Summary104 105**Philosophy**: Prefer unit tests over integration tests. Write unit-testable code by default.106 107**Unit tests** (fast, preferred):108 109- Test pure functions and business logic110- Extract business logic from infrastructure111- Use dependency injection112 113**Integration tests** (slow, use sparingly):114 115- Only for features that cannot be unit tested (virtual modules, full build pipeline)116- Always set unique `outDir` to avoid cache pollution117 118See [testing.md](testing.md) for complete patterns and examples.119 120## When NOT to Use This Skill121 122- **Bug triage**: Use the `triage` skill instead123- **GitHub Actions analysis**: Use the `analyze-github-action-logs` skill124- **Simple questions**: Just ask directly, don't load this skill125 126## Related Documentation127 128- Root: [/AGENTS.md](../../../AGENTS.md)129- Root: [/CONTRIBUTING.md](../../../CONTRIBUTING.md)130- Astro docs: https://docs.astro.build/131- Package: packages/astro/src/core/README.md132- Build plugins: packages/astro/src/core/build/plugins/README.md133