Cursor rule

1---
2globs: *.astro
3description: Astro component structure and organization best practices
4---
5 
6# Astro Component Structure
7 
8## Standard Component Structure
9 
10Follow this order for Astro component sections:
11 
12```astro
13---
14// 1. Imports first
15import { SomeService } from '../services/someService';
16import type { ComponentProps } from '../types/component';
17 
18// 2. Interface definitions
19interface Props {
20  symbol: string;
21  forceRefresh?: boolean;
22}
23 
24// 3. Props destructuring
25const { symbol, forceRefresh = false } = Astro.props;
26 
27// 4. Runtime/environment setup
28const db = (Astro.locals.runtime?.env?.DB as D1Database) || null;
29 
30// 5. Data fetching and business logic
31let data: { items: any[]; error?: string } = { items: [] };
32 
33if (db) {
34  try {
35    const service = SomeService.getInstance(db);
36    const items = await service.fetchData(symbol, forceRefresh);
37    data = { items };
38  } catch (err) {
39    data = { items: [], error: err instanceof Error ? err.message : 'Error' };
40  }
41}
42---
43 
44<!-- 6. HTML template -->
45<div class="component-container">
46  <!-- Component content here -->
47</div>
48 
49<!-- 7. Scoped styles -->
50<style>
51  .component-container {
52    /* Styles here */
53  }
54</style>
55 
56<!-- 8. Client-side scripts (only when necessary) -->
57<script>
58  // Minimal client-side enhancement only
59</script>
60```
61 
62## Component Best Practices
63 
64### Props Interface
65- Always define a `Props` interface for type safety
66- Use optional properties with defaults where appropriate
67- Keep props simple and focused
68 
69### Data Structure
70- Use consistent data structure pattern: `{ items: any[]; error?: string }`
71- Separate concerns: one data object per logical data source
72- Always include error states
73 
74### Template Patterns
75- Use conditional rendering with ternary operators
76- Provide meaningful fallbacks for empty states
77- Keep templates readable with proper indentation
78 
79### Error Handling in Templates
80```astro
81<div>
82  {data.error ? (
83    <p class="text-red-500">Error: {data.error}</p>
84  ) : data.items.length > 0 ? (
85    <div>
86      {data.items.map((item) => (
87        <div class="item">{item.name}</div>
88      ))}
89    </div>
90  ) : (
91    <p class="text-gray-500">No data available</p>
92  )}
93</div>
94```
95 
96## File Naming
97- Use snake_case for component files (following project convention)
98- Be descriptive: `historical_data_view.astro` not `history.astro`
99- Group related components in appropriate directories
100 
101## Import Organization
102```astro
103---
104// 1. External libraries
105import { z } from 'zod';
106 
107// 2. Internal services
108import { OptionsService } from '../services/optionsService';
109 
110// 3. Internal utilities
111import { formatDate } from '../utils/dateUtils';
112 
113// 4. Internal components
114import SearchForm from './searchForm.astro';
115 
116// 5. Types (last)
117import type { OptionData } from '../types/option';
118---
119```