Astro Project Rules

astrofrontendssg

Enforces Astro conventions including island architecture, content collections, SSG/SSR configuration, and component patterns for performance-first web development.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

## Astro Project Rules ### File & Directory Structure - `src/pages/` — file-based routing; `.astro`, `.md`, `.mdx` files become routes - `src/layouts/` — reusable layout components wrapping page content - `src/components/` — Astro and framework components - `src/content/` — content collections (blog posts, docs, etc.) - `src/lib/` — utilities, data fetching helpers, non-component logic - `public/` — static assets served as-is; do not import from here in components ### Component Rules - Prefer `.astro` components over framework components for static UI - Use framework components (React, Vue, Svelte) only when interactivity is required - Astro component frontmatter (between `---`) runs at build time on the server only - Never put browser APIs (`window`, `document`) in the Astro frontmatter - Pass only serializable props to framework components used as islands - Use `Astro.props` with TypeScript interface definition for all component props ### Islands Architecture - Add `client:load` only for components needed immediately on page load - Prefer `client:idle` for non-critical interactive widgets - Prefer `client:visible` for components below the fold - Use `client:only="react"` for components that cannot render on the server - Minimize the number of islands per page — each island is a JavaScript bundle ### Content Collections - Define all collections in `src/content/config.ts` with Zod schemas - Use `getCollection()` and `getEntry()` for type-safe content access - Validate frontmatter fields in the schema — never access unchecked frontmatter properties - Use `CollectionEntry<'name'>` type for content entry props - Slug field is auto-generated from filename; do not duplicate it in frontmatter ### Data Fetching - Fetch data in the Astro frontmatter (`---` block) for SSG and SSR pages - Use `Astro.request` for SSR-specific request data (headers, cookies) - Avoid fetching in client-side code when the data can be fetched at build time - Cache expensive fetches with build-time memoization or static generation ### SSG vs SSR - Default to SSG (`output: 'static'`) for content-heavy sites - Use `export const prerender = false` per-route to opt into SSR - Use `output: 'server'` globally only when most routes require SSR - Use `output: 'hybrid'` to mix prerendered and server-rendered routes ### Routing - Dynamic routes use `[param].astro` syntax; generate paths with `getStaticPaths()` - `getStaticPaths()` must return all possible `{ params }` at build time for SSG - Use `Astro.redirect()` for server-side redirects in SSR routes - Use `404.astro` for custom not-found pages ### Styling - Use scoped `<style>` blocks in `.astro` files to avoid CSS collisions - Use `:global()` only when explicitly targeting external or dynamic content - Prefer Tailwind CSS utility classes for consistency with design system - Never inline critical styles in `<head>` manually — Astro handles critical CSS ### Performance Rules - Every `<img>` must use Astro's `<Image>` component for automatic optimization - Avoid third-party scripts without `defer` or `async` attributes - Use `<ViewTransitions />` for smooth navigation without full page reloads - Minimize JavaScript in non-island components — Astro ships zero JS by default ### Anti-patterns - Do not use React's `useState`/`useEffect` in `.astro` files — use framework components - Do not fetch data inside client-side `<script>` tags when it can be done at build time - Do not hardcode absolute URLs — use `import.meta.env.SITE` for base URL - Do not skip `getStaticPaths()` for dynamic SSG routes — build will fail

CLI

npx mindaxis apply astro-rules --target cursor --scope project

Используется в паках

Astro Static

Fast Astro sites, zero JavaScript

Открыть пак →

← Правила