Cursor rule

1---
2globs: *.astro
3description: Performance optimization patterns for Astro applications
4---
5 
6# Astro Performance Patterns
7 
8## Server-Side vs Client-Side Decision Matrix
9 
10### ✅ Use Server-Side Rendering (SSR) For:
11- **Initial page data**: Historical data, user profiles, product listings
12- **SEO-critical content**: Meta information, structured data, primary content
13- **Static or slow-changing data**: Configuration, settings, reference data
14- **Database queries**: Direct database access for initial data load
15- **API aggregation**: Combining multiple API calls into single server request
16 
17### ✅ Use Client-Side Rendering (CSR) For:
18- **Real-time updates**: Live chat, stock prices, notification feeds
19- **User interactions**: Form validation, interactive filters, dynamic searches
20- **Progressive enhancement**: Adding interactivity to server-rendered content
21- **Client-only APIs**: Geolocation, camera, local storage, WebRTC
22- **Infinite scroll/pagination**: Loading additional content on demand
23 
24## Performance Optimization Patterns
25 
26### Data Prefetching in Frontmatter
27```astro
28---
29// ✅ GOOD: Aggregate multiple API calls server-side
30const [userData, postsData, commentsData] = await Promise.allSettled([
31  userService.getUser(userId),
32  postService.getPosts(userId),
33  commentService.getComments(userId)
34]);
35 
36// Transform results with error handling
37const user = userData.status === 'fulfilled' ? userData.value : null;
38const posts = postsData.status === 'fulfilled' ? postsData.value : [];
39const comments = commentsData.status === 'fulfilled' ? commentsData.value : [];
40---
41 
42<!-- ❌ AVOID: Multiple client-side API calls -->
43<!-- <script>
44  Promise.all([
45    fetch('/api/user'),
46    fetch('/api/posts'),
47    fetch('/api/comments')
48  ]).then(...)
49</script> -->
50```
51 
52### Conditional Loading Strategies
53```astro
54---
55interface Props {
56  priority: 'high' | 'low';
57  symbol: string;
58}
59 
60const { priority, symbol } = Astro.props;
61 
62// Load expensive data only for high-priority requests
63let expensiveData: any = null;
64if (priority === 'high') {
65  try {
66    expensiveData = await expensiveService.getDetailedAnalysis(symbol);
67  } catch (err) {
68    console.error('Failed to load detailed analysis:', err);
69  }
70}
71 
72// Always load basic data
73const basicData = await basicService.getQuickData(symbol);
74---
75 
76<div>
77  <!-- Always show basic data -->
78  <BasicDataDisplay data={basicData} />
79  
80  <!-- Conditionally show expensive data -->
81  {expensiveData && (
82    <DetailedAnalysis data={expensiveData} />
83  )}
84  
85  <!-- Client-side enhancement for low priority -->
86  {priority === 'low' && (
87    <button id="load-details" data-symbol={symbol}>
88      Load Detailed Analysis
89    </button>
90  )}
91</div>
92 
93{priority === 'low' && (
94  <script>
95    document.getElementById('load-details')?.addEventListener('click', async (e) => {
96      const symbol = e.target.dataset.symbol;
97      const response = await fetch(`/api/detailed-analysis?symbol=${symbol}`);
98      // Handle client-side loading for low priority
99    });
100  </script>
101)}
102```
103 
104### Caching Strategies
105```astro
106---
107// Use service-level caching for expensive operations
108const cacheKey = `analysis_${symbol}_${new Date().toDateString()}`;
109 
110let analysisData: any;
111try {
112  // Check cache first
113  analysisData = await cacheService.get(cacheKey);
114  
115  if (!analysisData) {
116    // Compute and cache
117    analysisData = await expensiveAnalysisService.analyze(symbol);
118    await cacheService.set(cacheKey, analysisData, 3600); // 1 hour cache
119  }
120} catch (err) {
121  console.error('Analysis cache error:', err);
122  analysisData = null;
123}
124---
125```
126 
127## Bundle Size Optimization
128 
129### Minimal Client-Side JavaScript
130```astro
131<!-- ✅ GOOD: Minimal client enhancement -->
132<button id="toggle-details" data-expanded="false">
133  Show Details
134</button>
135 
136<div id="details" class="hidden">
137  <!-- Server-rendered content -->
138</div>
139 
140<script>
141  // Simple DOM manipulation only
142  document.getElementById('toggle-details')?.addEventListener('click', (e) => {
143    const details = document.getElementById('details');
144    const expanded = e.target.dataset.expanded === 'true';
145    
146    details?.classList.toggle('hidden', expanded);
147    e.target.dataset.expanded = (!expanded).toString();
148    e.target.textContent = expanded ? 'Show Details' : 'Hide Details';
149  });
150</script>
151 
152<!-- ❌ AVOID: Heavy client-side frameworks for simple interactions -->
153```
154 
155### Lazy Loading with client:visible
156```astro
157---
158// Heavy component that should load only when visible
159import HeavyChart from './heavy_chart.astro';
160---
161 
162<div>
163  <!-- Critical above-the-fold content renders immediately -->
164  <CriticalContent />
165  
166  <!-- Heavy component loads only when scrolled into view -->
167  <HeavyChart client:visible />
168</div>
169```
170 
171## Database Query Optimization
172 
173### Efficient Data Loading
174```astro
175---
176// ✅ GOOD: Single optimized query
177const combinedData = await db.prepare(`
178  SELECT 
179    s.symbol, s.current_price,
180    COUNT(o.id) as option_count,
181    MAX(score.total_score) as max_score
182  FROM stock_snapshots s
183  LEFT JOIN option_snapshots o ON s.id = o.snapshot_id
184  LEFT JOIN option_score_snapshots score ON o.id = score.option_snapshot_id
185  WHERE s.symbol = ? AND s.created_at >= ?
186  GROUP BY s.id
187  ORDER BY s.created_at DESC
188  LIMIT 10
189`).bind(symbol, cutoffDate).all();
190 
191// ❌ AVOID: Multiple separate queries
192// const stocks = await getStocks(symbol);
193// const options = await getOptions(stockId);
194// const scores = await getScores(optionId);
195---
196```