Astro Framework Development Guidelines
A set of best practices and instructions for developing scalable web applications using the Astro framework, focusing on performance, maintainability, and accessibility:
Key Principles
- Prioritize static generation and minimal JavaScript for optimal performance.
- Leverage Astro’s partial hydration and multi-framework support effectively.
- Use descriptive variable names and follow Astro’s naming conventions.
- Organize files using Astro’s file-based routing system.
Astro Project Structure
- Use the recommended structure:
src/components/layouts/pages/styles/
public/astro.config.mjs
Component Development
- Create
.astrofiles for Astro components. - Use framework-specific components (React, Vue, Svelte) when necessary.
- Implement proper component composition and reusability.
Routing and Pages
- Utilize Astro’s file-based routing system in
src/pages/. - Implement dynamic routes using
[...slug].astrosyntax. - Use
getStaticPaths()for generating static pages with dynamic routes.
Content Management
- Use Markdown (.md) or MDX (.mdx) files for content-heavy pages.
- Leverage Astro’s built-in support for frontmatter in Markdown files.
Styling
- Use Astro’s scoped styling with tags in
.astrofiles. - Leverage global styles when necessary, importing them in layouts.
- Utilize CSS preprocessing with Sass or Less if required.
Performance Optimization
- Minimize use of client-side JavaScript; leverage Astro’s static generation.
- Use the
client:*directives judiciously for partial hydration. - Implement proper lazy loading for images and other assets.
Data Fetching
- Use Astro.props for passing data to components.
- Implement
getStaticPaths()for fetching data at build time. - Use Astro.glob() for working with local files efficiently.
SEO and Meta Tags
- Use Astro’s
<head>tag for adding meta information. - Implement canonical URLs for proper SEO.
- Use the
<SEO>component pattern for reusable SEO setups.
Integrations and Plugins
- Utilize Astro integrations for extending functionality (e.g.,
@astrojs/image). - Implement proper configuration for integrations in
astro.config.mjs.
Build and Deployment
- Optimize the build process using Astro’s build command.
- Implement proper environment variable handling for different environments.
- Use static hosting platforms compatible with Astro (Netlify, Vercel, etc.).
Styling with Tailwind CSS
- Integrate Tailwind CSS with Astro using
@astrojs/tailwind. - Use Tailwind utility classes extensively in Astro components.
Testing and Accessibility
- Implement unit tests for utility functions and helpers.
- Use end-to-end testing tools like Cypress for testing the built site.
- Ensure proper semantic HTML structure in Astro components.
Key Conventions
- Follow Astro’s Style Guide for consistent code formatting.
- Use TypeScript for enhanced type safety and developer experience.
- Implement proper error handling and logging.
Performance Metrics
- Prioritize Core Web Vitals (LCP, FID, CLS) in development.
- Use Lighthouse and WebPageTest for performance auditing.
Overview of .cursorrules prompt
The .cursorrules file provides guidelines and best practices for developers using JavaScript, TypeScript, and the Astro framework to build scalable web applications. It emphasizes writing concise and accurate technical responses, prioritizing static generation, and optimizing performance with minimal JavaScript. It outlines recommended project structures, component development, routing, and content management practices within Astro. The file stresses the use of scoped styling, performance optimization techniques, data fetching, SEO considerations, integrations, and deployment practices. It also advises best practices for styling with Tailwind CSS, implementing tests, ensuring accessibility, and maintaining key conventions. Performance metrics and monitoring tools are recommended to ensure optimal web application performance. Developers are encouraged to refer to Astro’s official documentation for detailed guidance.
