astro-developer
/astro-developer
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.
- Author
- withastro ↗
- Repository
- astro ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Quick Decision Matrix
- Critical Warnings
- Quick Command Reference
- Key File Paths
- Usage
- Architecture Quick Summary
- Testing Quick Summary
- When NOT to Use This Skill
- Related Documentation
SKILL.md preview
--- 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. --- # Astro Developer Skill Context-loading skill for AI agents and developers working in the Astro monorepo. Loads relevant documentation based on your task. ## Quick Decision Matrix **What are you doing?** → **Read these files:** | Task | Primary Docs | Supporting Docs | | -------------------------- | -------------------------------------------------------------------- | ---------------------------------- | | Adding a core feature | [architecture.md](architecture.md), [constraints.md](constraints.md) | [testing.md](testing.md) | | Fixing a bug | [debugging.md](debugging.md) | [architecture.md](architecture.md) | | Writing/fixing tests | [testing.md](testing.md) | [constraints.md](constraints.md) | | Creating an integration | Explore `packages/integrations/` for examples | [testing.md](testing.md) | | Understanding architecture | [architecture.md](architecture.md) | - | | Dealing with errors | [debugging.md](debugging.md), [constraints.md](constraints.md) | [testing.md](testing.md) | | Understanding constraints | [constraints.md](constraints.md) | [architecture.md](architecture.md) | ## Critical Warnings **Before you start, be aware of these common pitfalls:** 1. **Prefer Unit Tests**: Write unit-testable code by default. Use integration tests only when necessary → [testing.md](testing.md) 2. **Node.js API Restrictions**: Cannot use Node.js APIs in `runtime/` code → [constraints.md](constraints.md) 3. **Test Isolation**: Must set unique `outDir` for each integration test → [testing.md](testing.md) 4. **Runtime Boundaries**: Core vs Vite vs Browser execution contexts → [architecture.md](architecture.md) 5. **Prerelease Mode**: Changesets target `origin/next` branch (check `.changeset/config.json`) ## Quick Command Reference ```bash # 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 ``` ## 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](architecture.md) for details. ## Usage This skill loads relevant context—it doesn't orchestrate workflows. After loading appropriate docs: 1. Read the recommended files for your task 2. Apply the patterns and constraints described 3. Use the commands and file paths provided 4. 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](architecture.md) for complete details. ## 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](testing.md) for complete patterns and examples. ## 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 ## Related Documentation - Root: [/AGENTS.md](../../../AGENTS.md) - Root: [/CONTRIBUTING.md](../../../CONTRIBUTING.md) - Astro docs: https://docs.astro.build/ - Package: packages/astro/src/core/README.md - Build plugins: packages/astro/src/core/build/plugins/README.md
Files in this package (6)
- SKILL.md 6 KB
- architecture.md 14 KB
- constraints.md 13 KB
- debugging.md 14 KB
- testing.md 21 KB
- evals/evals.json 8 KB
Versions
The database has no other skills named astro-developer.
Identical content appears in 2 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 6e2f723e28a5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90astro-i18n
Use when implementing i18n in Astro — locale routing strategies, getRelativeLocaleUrl/getAbsoluteLocaleUrl, Astro.currentLocale, or hreflang with sitemap. - 100astro
Astro development standards and best practices for content-driven websites Triggers on: **/*.astro, **/*.ts, **/*.js, **/*.md, **/*.mdx - 90astro-guide
Use when editing or scaffolding Astro sites with islands architecture. Triggers on `.astro` files, `astro:content` imports, `Astro.props`, `client:` hydration directives, content-collection schemas, and on prompts about pages, layouts, MDX, content collections, image… - 100run-astro-audit
Use if conducting comprehensive Astro audits, running multi-wave subagent remediation, validating AST rules with Astro Sentinel, or managing serial merge queues. - 100astro-db
Use when doing database operations in an Astro project via Astro DB (defineDb, defineTable, db/config.ts, Turso). - 100astro
Skill for building with the Astro web framework. Helps create Astro components and pages, configure SSR adapters, set up content collections, deploy static sites, and manage project structure and CLI commands. Use when the user needs to work with Astro, mentions .astro files,…