Add rules for Astro

.cursor/rules/03-frameworks-and-libraries/3-astro.mdc

@@ -0,0 +1,78 @@
+---
+description: APPLY Astro.js framework standards WHEN developing with Astro
+globs: apps/frontend/src/**/*.astro,apps/frontend/src/**/*.js,apps/frontend/src/**/*.jsx,apps/frontend/src/**/*.ts,apps/frontend/src/**/*.tsx
+alwaysApply: false
+---
+
+Architecture:
+- Prefer TypeScript over JavaScript for all source files
+- Separate concerns between UI, state management, and business logic
+- Prefer conditions based on an object over switch statements or if/else blocks
+- Use a clear modular file structure
+- Use `src/pages` for routing only
+- Keep business logic out of routing layer
+- Place shared components in `src/components`
+- Place layouts in src/layouts
+- Use `src/content` for Markdown or CMS-driven content via `@astro/content`
+- Use `zod` for schema validation in forms, API endpoints, and content parsing
+- Prepare for Astro's internationalisation (i18n) features
+
+Components:
+- Keep components small and focused
+- Prefer `.astro` files for static markup and server-first logic
+- Use framework-based (React/Svelte/Vue) components only when needed for interactivity
+- Co-locate scoped styles with components
+
+Client Interactivity:
+- Avoid deeply nested reactivity when possible
+- Hydrate components only when needed using `client:*` directives
+- Always prefer client:load, client:visible, client:idle over client:only to limit JS hydration
+- Use Astro Islands wisely. Keep interactive components isolated and small
+- Use lightweight state libraries like `zustand`, `signals`
+- Prefer using native Javascript Proxies over `@tanstack/react-query`
+
+Performance:
+- Use `@astrojs/image` for image optimisation
+- Preload key assets (e.g., fonts) via `<link rel="preload">`
+- Avoid large JS bundles
+- Monitor bundle size with `astro check`, `vite-plugin-analyzer`
+
+Styling:
+- Use Scoped CSS Modules consistently
+- Avoid global CSS unless theming or utility styles are required
+- Always purge unused styles in production
+
+Routing:
+- Use file-based routing
+- Avoid dynamic routing unless essential
+- Enable prefetching
+
+SEO:
+- Include SEO tags (`<title>`, `<meta name>`, Open Graph tags) on all pages
+- Use `@astro/head` or shared SEO component
+- Generate sitemap and robots.txt with `astro-sitemap`, `astro-robots-txt`
+
+Content:
+- Prefer Markdown/MDX content via content collections
+- Use `zod` and `defineCollection` to validate content schema
+- Use the global `fetch()` function in the component script to make HTTP requests to APIs using the full URL
+- Take advantage of top-level `await` inside of the Astro component script
+
+Plugins:
+- Use only official or vetted Astro integrations
+
+Analytics:
+- Add via inline `<script>` or packages like `astro-plausible`
+
+Auth:
+- Handle via JS SDKs or edge function integrations
+
+Build:
+- Use Astro's official adapters for server rendering at request time
+- Always verify deployment in a staging environment
+- Enable hybrid rendering if needed (`output: 'hybrid'`)
+
+Testing:
+- Use ESLint with Astro plugin, Prettier, and Stylelint
+- Test with Playwright
+- Run `astro check` in CI and pre-commit