Skip to content

project rulesFrontendastro

Astro Rules

Project rules for Astro sites: zero-JS by default, islands with the right client directive, typed content collections and optimized images.

npx workspacetemplates add astro-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file21 lines · 1.4 KBFile
# Project rules: Astro

## Structure
- Pages live in `src/pages`, shared layout in `src/layouts`, reusable markup in `.astro` components. Use a React, Svelte or Vue component only when it needs client state.
- Keep TypeScript strict. Extend `astro/tsconfigs/strict` and type component props with an `interface Props`.

## Islands and hydration
- Default to no client JavaScript. Choose the lightest directive: `client:visible` for below-the-fold widgets, `client:idle` for low priority, `client:only` only when SSR cannot work. Justify any `client:load` in a comment.
- Pass serializable props only. Share state between islands with a small store, not through the DOM.

## Content and data
- Put Markdown, MDX and JSON in content collections with a Zod schema in `src/content.config.ts`. Read them with `getCollection`, never by importing paths by hand.
- Fetch remote data in frontmatter at build time. Mark a route `prerender = false` only when it truly needs request data.

## Images and assets
- Use `<Image />` or `<Picture />` from `astro:assets` with width, height and alt text. Keep originals in `src`, not `public`.
- Scope styles inside the component; avoid global CSS except a tokens file.

## Before finishing
- Run `astro check`, then `astro build`. Fix every type error and broken link; do not suppress with `any`.
- Add a sitemap and a canonical URL in the shared layout.

What it does

These rules teach an agent to treat Astro as a content-first framework where pages ship no JavaScript unless an island asks for it. They settle where data loads, when a framework component is justified and how images are served.

Use them to stop generated code from sprinkling client:load on everything or reaching for fetch inside components when a content collection would give typed, validated data.

Example

you › Add a blog with tags and an RSS feed

agent › The agent defines a posts collection with a schema, builds list and tag pages from getCollection, adds an RSS endpoint and runs astro check and build.

Questions

Does this assume server rendering?
No. It prefers static output and only allows on-demand routes when a page needs request data.
Can I use it with React islands?
Yes. The hydration rules apply to any framework component you mount inside an Astro page.
  • .NET Blazor Rules

    Project rulescsharp

    Free
  • Angular Rules

    Project rulesangular

    Free
  • Electron Rules

    Project ruleselectron

    Free
  • Next.js App Router Rules

    Project rulesnextjs

    Free