# Claude Code with Astro: a practical setup guide

URL: https://agentvera.dev/en/blog/claude-code-for-astro/ · Published: 2026-11-01

Learn how to configure Claude Code for Astro: CLAUDE.md setup, content collections, islands, static builds, common pitfalls, and testing commands.

**In short:**

- Add a CLAUDE.md with Astro commands, paths, and static-build rules so Claude Code works safely from the first prompt.
- Use plan mode and small batches for content collections, dynamic routes, and island changes; run astro check and build after each step.
- Review diff and build output closely for missing getStaticPaths exports, stale content types, and overly eager client directives.

Claude Code is Anthropic’s terminal coding agent; you start it with `claude` in an Astro project folder and it reads, edits, and runs commands in that directory. This guide shows how to make Claude Code effective for Astro work: content collections, islands, static builds, and integrations. It assumes you know Astro and want concrete setup, prompts, and verification steps, not generic AI advice.

## Why Claude Code fits Astro projects well
Astro projects separate concerns clearly: `.astro` files combine markup, frontmatter, and component composition; content collections give typed data; islands isolate client JavaScript. Claude Code can use those boundaries because they are explicit in the repo. It reads `src/content/config.ts`, understands collection schemas, and can update both schema and route files together. Astro’s static-first model makes many edits local with predictable effects, so the agent can iterate quickly with `astro check` and `pnpm build`. It is especially useful for repetitive edits across many content entries, layout refactors, and island conversions. Because Astro components are mostly declarative, the agent can locate component boundaries quickly and avoid editing generated output. The static build step gives a deterministic check, so the agent can learn from build output and fix issues without guessing.

## Preparing your Astro project for Claude Code
Claude Code reads `CLAUDE.md` at the project root for instructions. Keep it short and Astro-specific: commands, folder conventions, and rules that prevent the agent from breaking static builds or content types. Avoid generic advice; state exact commands and paths. The file should tell the agent which directories are source and which are generated, and which island framework integrations are installed so it does not try to add a component that requires an uninstalled integration. For more on what belongs in project instructions, see [Claude Code best practices: a practical checklist](/en/blog/claude-code-best-practices/).

```markdown
# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Preview: `pnpm preview`
- Lint: `pnpm lint`
- Check: `pnpm astro check`

## Project layout
- `src/content/` — content collections, schema in `src/content/config.ts`
- `src/components/` — reusable `.astro` and framework components
- `src/components/islands/` — components with `client:*` directives
- `src/pages/` — file-based routes
- `src/layouts/` — layout components
- `src/styles/` — global CSS
- `public/` — static assets served as-is

## Rules
- Use `astro:content` and typed `getCollection()`; do not read content with raw `fs`.
- Keep client-side logic in islands under `src/components/islands/`.
- For static builds, avoid server-only APIs unless an adapter is configured.
- Run `pnpm astro check` after any change that touches content schemas, routes, or component props.
- Do not edit generated files in `.astro/` or `dist/`.
```
The example uses pnpm; use the package manager your repo actually uses. Include `astro check` as a non-negotiable verification step. If you use an adapter for SSR, add the adapter-specific command and note which routes are server-rendered.

## A safe iteration loop for Astro changes
Do not ask for a large rewrite at once. Start with plan mode for cross-cutting changes, then let the agent make small edits, run verification, and show a diff. An effective loop is: state the goal and constraints; ask for a plan before changes; review the plan against Astro’s static build and content collection rules; approve small edits; run `pnpm astro check` and `pnpm build`; inspect `git diff`; repeat. After each change, ask the agent to summarize which files it touched and why, so the review stays focused. For complex refactors, see [Claude Code plan mode: plan first, then let it build](/en/blog/claude-code-plan-mode/).

Example prompts for typical Astro tasks:
- Add a `notes` content collection to `src/content/config.ts` with fields `title`, `publishedAt`, `draft`, and `tags`. Then add two sample entries under `src/content/notes/`.
- Create `src/pages/notes/[...slug].astro` that uses `getStaticPaths` and `getCollection('notes')` to statically render each note. Sort by `publishedAt` descending and skip entries where `draft` is true.
- Refactor the header search box in `src/components/Header.astro` into a React island with `client:idle`, keeping the existing class names and moving state into the island component.
- Run `pnpm astro check`, fix every error it reports, and explain why each change was needed in the final commit message.
- Review the last build output for warnings about missing client directives or large islands; propose specific component changes to reduce JavaScript shipped to the client.

## Common Astro tasks and the pitfalls to watch
Claude Code handles many Astro-specific jobs well: adding or updating content collections, generating index and detail routes, updating layout components, converting static markup to islands, fixing type errors after schema changes, writing frontmatter validation, and moving repeated components into layouts.

Where to watch it closely:

| Area | High-risk change to review |
| --- | --- |
| Content collection schema | Changing field types without updating entries or queries |
| Dynamic route | Missing `getStaticPaths` export or wrong `params` return |
| Island directive | Using `client:load` on a component used in many pages |
| Static build | Using server-only APIs without enabling an adapter |

- Content collection schema changes require a full `pnpm astro check`; otherwise generated types in `.astro` can be stale.
- Static routes with `getStaticPaths` must be exported from `.astro` pages; the agent may forget when copying dynamic route patterns.
- Client directives such as `client:load` or `client:idle` on a shared component can add JavaScript to many pages unintentionally.
- Astro frontmatter cannot import server-only Node APIs in static builds unless behind an adapter; watch for accidental `fs`, `path`, or `process` use.
- Content collections with `glob()` rely on file structure; renaming files without updating queries can produce empty pages at build time.
- Framework islands require the integration installed; an agent may write a React, Preact, or Vue component without checking `astro.config.mjs`.

## Testing and verifying Astro output
Always run `pnpm astro check` before build, and `pnpm build` before merging. The agent can run these commands itself, but you should review the output. `astro check` catches type errors in templates and frontmatter, including content collection schema mismatches. `pnpm build` verifies static route generation, island bundling, and that `getStaticPaths` returned expected paths. If the repo has a `test` script, run it after build changes.

| Command | What it verifies |
| --- | --- |
| `pnpm astro check` | Template/frontmatter types, collection schemas, prop types |
| `pnpm build` | Static generation, route collection, client island bundling |
| `pnpm dev` | Live behavior, hydration, client-side interactivity |
| `pnpm lint` | Lint rules across scripts and framework components |

After a build, inspect `dist/` for generated HTML and `_astro/` for bundled islands. If the project has an adapter, run the preview command and hit a few routes before accepting the change.

## Parallel agents on an Astro repo with AgentVera
On an Astro project, AgentVera helps when one agent updates content collection schemas while another refactors islands or fixes static build warnings. It runs real CLI agents in separate git worktrees, so parallel work does not overwrite the same `.astro` files. Automatic code review after each turn catches Astro-specific mistakes such as a missing `getStaticPaths` export or a schema change that breaks `getCollection` calls, and checkpoints let you undo a bad edit quickly. Token budgets prevent long build and debug loops from exhausting your limit. For more, see [How to run multiple Claude Code agents in parallel](/en/blog/run-multiple-claude-code-agents/).

## Final notes on Claude Code and Astro
Claude Code is most useful on Astro projects when you give it a focused CLAUDE.md, use plan mode for complex changes, and verify with `astro check` and `pnpm build`. Keep an eye on content collection types, static path exports, and island client directives. With those guardrails, it handles repetitive Astro work reliably.

## Frequently asked questions

**How do I set up Claude Code for an Astro project?** Install Claude Code and run claude in your Astro project directory. Add a CLAUDE.md file with your package manager commands, folder layout, and Astro-specific rules such as using astro:content and running pnpm astro check after schema changes.

**Can Claude Code handle Astro content collections?** Yes. Claude Code can read and edit src/content/config.ts, add entries to src/content/, and update routes that call getCollection(). You should still run pnpm astro check and pnpm build to verify that schemas, frontmatter, and generated pages stay in sync.

**Does Claude Code understand Astro islands and client directives?** It understands the concept of islands and can convert static markup into framework components with client:load, client:idle, or client:visible. Review the changes carefully, because a misplaced client directive can add JavaScript to many pages or cause hydration errors.

**What is the best workflow for using Claude Code on a static Astro build?** Use plan mode for larger changes, ask for small edits, and run pnpm astro check and pnpm build after each step. Inspect git diff and watch for missing getStaticPaths exports, server-only APIs, and content collection schema mismatches.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/