Cursor rule

1---
2globs: *.astro
3description: Astro server-side rendering best practices and patterns
4---
5 
6# Astro SSR Best Practices
7 
8## Prefer Server-Side Rendering Over Client-Side
9 
10- **Always prefer SSR**: Use Astro frontmatter for data fetching instead of client-side JavaScript when possible
11- **Move API calls to frontmatter**: Fetch data during build/server time rather than in `<script>` tags
12- **Eliminate loading states**: Server-rendered content appears immediately without spinners or skeleton screens
13- **Improve SEO**: Search engines can index server-rendered content
14 
15## Example Pattern
16 
17```astro
18---
19// ✅ GOOD: Server-side data fetching
20import { SomeService } from '../services/someService';
21 
22const db = (Astro.locals.runtime?.env?.DB as D1Database) || null;
23let data: { items: any[]; error?: string } = { items: [] };
24 
25if (db) {
26  try {
27    const service = SomeService.getInstance(db);
28    const items = await service.fetchData();
29    data = { items };
30  } catch (err) {
31    data = { items: [], error: err instanceof Error ? err.message : 'Unknown error' };
32  }
33}
34---
35 
36<div>
37  {data.error ? (
38    <p class="text-red-500">Error: {data.error}</p>
39  ) : data.items.length > 0 ? (
40    <div>
41      {data.items.map((item) => (
42        <div>{item.name}</div>
43      ))}
44    </div>
45  ) : (
46    <p>No data available</p>
47  )}
48</div>
49 
50<!-- ❌ AVOID: Client-side fetching for initial data -->
51<!-- <script>
52  fetch('/api/data').then(response => {
53    // Don't do this for initial page data
54  });
55</script> -->
56```
57 
58## When to Use Client-Side JavaScript
59 
60- **Interactive features**: User interactions, form submissions, dynamic updates
61- **Real-time updates**: WebSocket connections, polling for live data
62- **Progressive enhancement**: Adding interactivity to server-rendered content
63- **Client-only APIs**: Browser APIs like geolocation, camera, etc.