diff --git a/.cursor/rules/03-frameworks-and-libraries/3-astro.mdc b/.cursor/rules/03-frameworks-and-libraries/3-astro.mdc new file mode 100644 index 0000000..6069859 --- /dev/null +++ b/.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 `` +- 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 (`