astro-monorepo

name	astro-monorepo
description	Guidelines for working on the Astro framework monorepo - covers build system, testing, coding conventions, and contribution workflow. Use when contributing to withastro/astro.
license	BSD-3-Clause
metadata	{"author":"matthewp","version":"1.0"}

Astro Monorepo Development Guide

Use this skill when working on the Astro framework monorepo.

Project Structure

astro/
├── packages/           # Core packages and integrations
│   ├── astro/          # Core Astro framework
│   ├── create-astro/   # CLI scaffolding tool
│   ├── integrations/   # Framework integrations (react, vue, svelte, etc.)
│   ├── language-tools/ # VS Code extension, language server
│   ├── markdown/       # Markdown processing
│   ├── db/             # Astro DB
│   └── ...
├── examples/           # Example Astro projects
├── benchmark/          # Performance benchmarks
├── scripts/            # Build and utility scripts (astro-scripts)
└── .changeset/         # Changeset configuration

Testing

Test Framework

• Primary: node:test (native Node.js test runner)
• E2E: Playwright (Chromium + Firefox)
• Assertions: node:assert/strict

Running Individual Tests

For most tests, run them directly with Node:

node packages/astro/test/astro-component.test.js

This is the fastest way to run a single test file during development.

Running E2E Tests

E2E tests use Playwright. To run a specific E2E test by name:

# From root - runs test matching the pattern
pnpm run test:e2e:match "test name pattern"

# Or from packages/astro
cd packages/astro
pnpm run test:e2e:match "test name pattern"

This runs playwright test -g "pattern" which matches against test names.

Test Patterns

import assert from "node:assert/strict";
import { describe, it, before, after } from "node:test";
import { loadFixture } from "./test-utils.js";

describe("Feature", () => {
  let fixture;

  before(async () => {
    fixture = await loadFixture({ root: "./fixtures/my-test/" });
    await fixture.build();
  });

  it("should work", async () => {
    const html = await fixture.readFile("/index.html");
    assert.ok(html.includes("expected content"));
  });
});

Important: Use a custom outDir per test to avoid cache conflicts between tests.

Runtime Code Restrictions

The codebase has three distinct runtime contexts:

1. Node.js (src/core/) - Build/dev commands, can use any Node.js APIs
2. Inside Vite (src/runtime/server/) - SSR execution, some Node.js restrictions
3. Browser (src/runtime/client/) - Client hydration, no Node.js APIs

CRITICAL: Code in runtime/ folders or runtime.ts files must be runtime-agnostic:

• NO direct node: imports (breaks Cloudflare, Deno, etc.)
• Node.js APIs allowed in Vite plugins but NOT in virtual modules
• Test runtime code works in non-Node environments

Contribution Workflow

Git

Do not stage or commit changes unless explicitly asked to.

Changesets

Required for any package changes (not needed for examples/*):

pnpm exec changeset

Select affected packages, bump type (patch/minor/major), and write a description.

Pull Requests

When creating a pull request, use the template at .github/PULL_REQUEST_TEMPLATE.md. The PR body must include:

1. Changes - Short, concise bullet points describing what changed. Include before/after screenshots if relevant.
2. Testing - Explain how the change was tested. If no tests were added, explain why.
3. Docs - Note if docs are needed. Tag @withastro/maintainers-docs for feedback if unsure.

Don't forget to run pnpm exec changeset before submitting!

Working with GitHub Issues

Identifying URL Types

Regular issue URL:

https://github.com/withastro/astro/issues/14481
                                       ^^^^^^
                                       Issue number

Project board item URL:

https://github.com/orgs/withastro/projects/21/views/1?pane=issue&itemId=154871753
                   ^^^^           ^^^^^^^^                       ^^^^^^^^^^^^^^^^
                   "orgs"         Project #                      Project item ID (NOT an issue number)

Key differences:

• Regular issues: /repos/ or /{owner}/{repo}/issues/{number}
• Project items: /orgs/{org}/projects/{number} with itemId query param
• Project items can be draft issues (no linked repo issue), linked issues, or pull requests

Fetching Regular Issues

Use gh issue view for regular repository issues:

# Fetch a specific issue by number
gh issue view 14481 --repo withastro/astro

# Fetch with full body content in JSON format
gh issue view 14481 --repo withastro/astro --json title,body,url,labels,state

# List recent issues
gh issue list --repo withastro/astro --limit 20

Fetching Project Board Items

Project board URLs require GraphQL. The itemId in the URL is a project-specific database ID, not an issue number.

# Fetch a specific project item by its itemId (e.g., 154871753)
gh api graphql -f query='
query {
  organization(login: "withastro") {
    projectV2(number: 21) {
      items(first: 100) {
        nodes {
          databaseId
          type
          fieldValues(first: 20) {
            nodes {
              ... on ProjectV2ItemFieldTextValue {
                text
                field { ... on ProjectV2FieldCommon { name } }
              }
              ... on ProjectV2ItemFieldSingleSelectValue {
                name
                field { ... on ProjectV2FieldCommon { name } }
              }
            }
          }
          content {
            ... on Issue {
              title
              body
              url
              number
            }
            ... on DraftIssue {
              title
              body
            }
          }
        }
      }
    }
  }
}' | jq '.data.organization.projectV2.items.nodes[] | select(.databaseId == 154871753)'

Important: Project items with "type": "DRAFT_ISSUE" have no linked repository issue - their content is only in the DraftIssue fragment. Items with "type": "ISSUE" are linked to real repo issues.

Common Issue Queries

# Search for issues by label
gh issue list --repo withastro/astro --label "bug" --limit 20

# Search issues by text
gh issue list --repo withastro/astro --search "cloudflare adapter"

# Get issue comments
gh api repos/withastro/astro/issues/14481/comments

Downloading StackBlitz Reproductions

Bug reports often include StackBlitz reproductions. Use stackblitz-clone to download them:

# Clone a StackBlitz project to a directory
npx stackblitz-clone https://stackblitz.com/edit/project-id

# Clone to a specific directory
npx stackblitz-clone https://stackblitz.com/edit/project-id ./my-repro

You can also change the URL domain from stackblitz.com to stackblitz.zip to download directly:

Original:  https://stackblitz.com/edit/nuxt-starter-k7spa3r4
Download:  https://stackblitz.zip/edit/nuxt-starter-k7spa3r4