From 6cc2025a0f32deda72993724c12b5824438e2b2a Mon Sep 17 00:00:00 2001 From: Damien TIVELET Date: Mon, 14 Jul 2025 16:40:40 +0200 Subject: [PATCH] Add rules for Astro --- .../03-frameworks-and-libraries/3-astro.mdc | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 .cursor/rules/03-frameworks-and-libraries/3-astro.mdc 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 (``, `<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