// 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.
| name | astro-developer |
| description | 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. |
Context-loading skill for AI agents and developers working in the Astro monorepo. Loads relevant documentation based on your task.
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 |
Before you start, be aware of these common pitfalls:
runtime/ code → constraints.mdoutDir for each integration test → testing.mdorigin/next branch (check .changeset/config.json)# Development
pnpm install # Install (root only)
pnpm run build # Build all packages
pnpm run dev # Watch mode
pnpm run lint # Lint codebase
# 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
# Examples
pnpm --filter @example/minimal run dev # Run example
# Changesets
pnpm exec changeset --empty # Create changeset, no interactive mode
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.
This skill loads relevant context—it doesn't orchestrate workflows. After loading appropriate docs:
Three Execution Contexts:
Five Pipeline Types:
astro dev with Vite loader systemastro dev without runtime module loading (Cloudflare adapter)astro build + prerenderingSee architecture.md for complete details.
Philosophy: Prefer unit tests over integration tests. Write unit-testable code by default.
Unit tests (fast, preferred):
Integration tests (slow, use sparingly):
outDir to avoid cache pollutionSee testing.md for complete patterns and examples.
triage skill insteadanalyze-github-action-logs skillTriage a bug report. Reproduces the bug, diagnoses the root cause, verifies whether the behavior is intentional, and attempts a fix. Use when asked to "triage issue
Create a changeset for the Astro monorepo. Use this skill whenever you need to add a changeset file to a PR, write a changelog entry, or document a package version bump. Also trigger when the user says "add a changeset", "write a changeset", "create a changeset", or when another skill instructs you to create a changeset.
Write and update Astro pull requests with reviewer-friendly titles and high-signal bodies. Trigger whenever the user asks to create a PR, open a PR, draft a PR, update PR title/body, or write PR notes/summary/description.
Analyze recent GitHub Actions workflow runs to identify patterns, mistakes, and improvements. Use when asked to "analyze workflow logs", "review action runs", or "analyze GitHub Actions".
