TypeScript 6,540 FILES 10 FINDINGS

HOW ASTRO
ACTUALLY WORKS

The web framework for content-driven websites. Conventions, patterns, and architecture extracted from the withastro/astro repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Validation: Zod schemas Testing: Node.js built-in test runner Integrations: packages/integrations/

WHAT_MATTERS

→
astro.ts is a hub file (imported by 88 files) — changes here ripple everywhere
→
17 third-party integrations under packages/integrations/ — each has its own directory
→
Circular import chains detected — avoid adding to these cycles

KEY_FINDINGS

This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.

HIGH

Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern.

HIGH

Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.

HIGH

5 barrel export files found

Use Zod schemas for validation. This is the project's standard validation approach.

HIGH

5 files use Zod

Tests use Node.js built-in test runner.

HIGH

15 test files

UI components live in: packages/integrations/vue/test/fixtures/ directories.

HIGH

3 component directories

Third-party integrations live under packages/integrations/ (web-vitals, vue, vercel, tailwind, svelte, solid, ...). Each integration has its own directory.

HIGH

17 integrations found

Hub files: packages/astro/src/types/astro.ts (88 files); packages/astro/src/core/errors/index.ts (71 files); packages/astro/src/types/public/internal.ts (68 files); packages/astro/src/core/logger/core.ts (67 files); packages/astro/src/types/public/config.ts (55 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: shiki.ts → types.ts; generate-sitemap.ts → index.ts; index.ts → validate-options.ts. Avoid adding to these cycles.

HIGH

54 dead code candidates.

HIGH

smart_toy USING_AI_TOOLS

→don't guess validation approach — Astro uses Zod
→check file importance before editing hub files (astro.ts has 88 dependents)
→integrations live under packages/integrations/ — don't create new top-level packages

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **validation:** Zod schemas
- **testing:** Node.js built-in test runner
- **routing:** Integrations under packages/integrations/

## Commands

- **Dev:** `turbo run dev`
- **Build:** `turbo run build`
- **Test:** `pnpm run test:astro`
- **Lint:** `biome lint`

## Critical Constraints

- **Monorepo:** This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.
- **Testing:** Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern.
- **Core modules:** Hub files (most depended on): packages/astro/src/types/astro.ts (88 files); packages/astro/src/core/errors/index.ts (71 files); packages/astro/src/types/public/internal.ts (68 files); packages/astro/src/core/logger/core.ts (67 files); packages/astro/src/types/public/config.ts (55 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular import chains detected: shiki.ts &rarr; types.ts; generate-sitemap.ts &rarr; index.ts; index.ts &rarr; validate-options.ts. Avoid adding to these cycles.

## Stack

Vite + React, Express, Fastify, TypeScript

## Core Modules (by structural importance)

- `packages/astro/src/assets/fonts/types.ts`
- `packages/astro/src/types/public/internal.ts`
- `packages/astro/src/core/errors/index.ts`

## Conventions & Patterns

- **Import conventions:** Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.
- **Dominant patterns:**
- Use Zod schemas for validation. This is the project's standard validation approach.
- Tests use Node.js built-in test runner.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

NEXT.JS HONO

HOW ASTROACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW ASTRO
ACTUALLY WORKS