BB SkillsFind a workflow. Make it your own.
Create account
New here? Start with the guide ↗
Browse sections ＋
Official Astro Monorepo Development Guide / Package file
READ-ONLY PACKAGE PREVIEW

astro-developer/SKILL.md

Version 28e74103fe3d.bb1 · MIT. This preview displays packaged text and does not execute code. Treat the contents as untrusted instructions.

← Return to resource and package checksum

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.

Independent BB Skills packaging and recorded scope (2026-10-08)

Official Astro monorepo contributor guide, fixed repository snapshot 28e74103fe3d999a56ae3404b5fe67a1ad6d8013. This is not a website-generation skill or a versioned Astro release. Thirteen original files, including six skill files, linked repository context, the actual Biome configuration and complete MIT notice, are retained unchanged under repository-context. The original primary instructions remain at repository-context/.agents/skills/astro-developer/SKILL.md. Only local link targets in the primary copy below are adjusted for this package; the original text is preserved separately. Evaluation prompts are retained as source material, not executed.

Independent local evidence records 46 observations across nine original documentation blocks with Node 24.10.0, Biome 2.5.3 and separately installed Astro 7.3.7. Node type erasure is experimental and is not a TypeScript typecheck. Synthetic imports and input files are explicitly provided by the runner. The unchanged Markdown unit assertion fails because its implementation retains a leading newline; the unchanged manifest unit assertion passes. A dual buildRoutes comparison also fails ESM parsing. These expected counterexamples are recorded, not silently rewritten.

The exact upstream Biome configuration reports Node API diagnostics in tested runtime folders and runtime-named files. Other lint diagnostics remain separate; zero errors from one rule does not mean a complete lint pass. The original bad virtual-module plugin emits a Node import; its emitted code is linted but its file read is not executed. Pure/configuration/Markdown/manifest functions and original file-reading plugin hooks use only independent synthetic data. Shared nested references and missing-frontmatter behavior are recorded.

Two real standalone Astro builds use the unchanged original JSON virtual-module plugin. Synthetic pages render different inputs in separate output and cache directories. The first output stays unchanged after the second build; generated title escaping, English HTML, one H1 and fixture canonical are checked. No monorepo loadFixture cache-pollution reproduction, browser hydration, edge adapter or all-pipeline compatibility claim follows. The build API is experimental. JavaScript HTTP/socket connections are denied by an independent preload during the builds; telemetry is disabled and zero attempts were recorded.

No account, database, real credential, production data, paid API or complete AI-client execution is involved. Installing locked dependencies separately contacts the free public registry. Full Astro checkouts and their current contributor instructions remain necessary for framework contributions; retained context is not the full monorepo. Installed dependencies, generated outputs and binaries are excluded from the download. Inspect examples/README.md and fixture-evidence.json for reproduction and limits. runtime_tested is false.

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, 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

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
  2. Node.js API Restrictions: Cannot use Node.js APIs in runtime/ code → constraints.md
  3. Test Isolation: Must set unique outDir for each integration test → testing.md
  4. Runtime Boundaries: Core vs Vite vs Browser execution contexts → architecture.md
  5. Prerelease Mode: Changesets target origin/next branch (check .changeset/config.json)

Quick Command Reference

# 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 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 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 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
  • Root: /AGENTS.md
  • Root: /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