-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path.cursorrules
262 lines (220 loc) · 12.8 KB
/
.cursorrules
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
You are an expert in TypeScript, Astro framework, Tailwind CSS, and modern web development.
---
# Key Principles
- **Write Concise and Technical Code**: Ensure your code is clear, efficient, and adheres to modern web development standards.
- **Leverage Astro Strengths**: Utilize Astro static site generation, partial hydration, and content-focused approach for optimal performance and SEO.
- **Prioritize Performance and SEO**: Aim for minimal JavaScript, fast load times, efficient resource management, and implement SEO best practices.
- **Produce High-Quality Content**: Focus on creating valuable, informative, and relevant content that resonates with your target audience.
- **Use Descriptive Naming**: Adopt clear and descriptive variable and function names.
- **Organize Files Logically**: Structure your project using Astro file-based routing and component system, ensuring consistency and maintainability.
---
# Project Structure
- **Recommended Astro Project Layout**:
```
- src/
- components/
- config/ # Configuration files for components and features
- content/
- layouts/
- pages/
- styles/ # Global and component-specific styles
- types/ # TypeScript type definitions
- utils/ # Utility functions and helpers
- public/
- astro.config.mjs
- tailwind.config.cjs
- src/env.d.ts # Environment and global type declarations
- src/types.ts # Central type definitions index
```
- **Components**: Place reusable UI components in `src/components/`.
- **Config**: Store component and feature configurations in `src/config/*.ts`:
- Use `Components.ts` for Astro component configurations
- Each config file should export constants used throughout the project
- Scripts should use site config constants defined in `/src/config/*.ts`
- **Types**:
- Place all TypeScript interfaces and types in `src/types/*.ts`
- Always reference new type files in `/src/types.ts`
- Maintain type definitions for component props, utilities, and configurations
- **Utils**:
- Store all utility functions in `/src/utils/*.ts`
- Ensure utility scripts are written in TypeScript, not JavaScript
- **Layouts**: Store layout components in `src/layouts/` for consistent page structure
- **Pages**: Organize page components in `src/pages/` using Astro routing conventions
- **Styles**: Keep all CSS files in `src/styles/*.css`
- **Content**: Store content files like Markdown or MDX in `src/content/`
---
# Code Style and Structure
- **Functional Programming**: Use functional and declarative programming patterns.
- **Avoid Unnecessary Complexity**: Keep components and functions focused, avoiding over-engineering.
- **TypeScript First**: Use TypeScript for type safety and enhanced developer experience.
- **Modularization**: Break down code into reusable modules and components.
- **Comments and Documentation**: Write meaningful comments and maintain clear documentation.
---
# Naming Conventions
- **Files and Folders**: Use kebab-case for file and folder names (e.g., `user-profile.astro`).
- **Components**: Use PascalCase for component names (e.g., `UserProfile`).
- **Variables and Functions**: Use camelCase (e.g., `fetchData`, `isLoaded`).
- **Constants**: Use UPPER_SNAKE_CASE for constants (e.g., `MAX_ITEMS`).
- **Props and Events**: Prefix boolean props with `is` or `has` (e.g., `isActive`, `hasError`).
---
# TypeScript and Development Standards
- **TypeScript-First Development**:
- Write all scripts in TypeScript, never JavaScript
- Utilize `/src/env.d.ts` for environment and global type declarations
- Create and maintain comprehensive type definitions in `/src/types/`
- Reference all type files in the central `/src/types.ts` index
- Whenever creating new TypeScript code or changing existing code, look around in `/src/types/*.ts` and create TypeScript types there as needed. If you create a new type file, don't forget to reference it in `/src/types.ts`**
- **Astro-Specific Guidelines**:
- This project is built with Astro and doesn't contain any React. Avoid writing any React code or TSX syntax
- Use `.astro` files for components instead of React components
- Leverage Astro's built-in features instead of React alternatives
- **Project Integration**:
- Ensure new files and changed files are properly referenced from other parts of the Astro/TypeScript project. Never create files in isolation.
- Use configuration constants from `/src/config/` in components and scripts
- **Code Organization**:
- Place all utility functions in `/src/utils/*.ts`
- Keep styles in `/src/styles/*.css`
- Maintain type definitions in `/src/types/*.ts`
---
# TypeScript Usage
- **Strict Mode**: Enable strict mode in your `tsconfig.json` for better type checking.
- **Interfaces over Types**: Prefer `interface` declarations over `type` aliases for object shapes.
- **Avoid `any` and `unknown`**: Strive for precise typings; avoid using `any` or `unknown`.
- **Generics**: Use generics for functions and components when appropriate.
- **Type Assertions**: Avoid using `as` for type assertions unless necessary.
---
# Astro Best Practices
- **Component Development**:
- Use `.astro` files for components.
- Utilize Astro component props for data passing.
- **Use Layouts for Consistency**: Implement layout components in `src/layouts/` to ensure a consistent header, footer, and main content across pages.
- Leverage Astro built-in components and features.
- **Routing and Pages**:
- Use file-based routing in `src/pages/`.
- Implement dynamic routes with `[param].astro` syntax.
- Handle 404 errors with a custom `404.astro` page.
- **Content Management**:
- Use Markdown (`.md`) or MDX (`.mdx`) files for content-heavy pages.
- Leverage Astro support for frontmatter in Markdown files.
- Implement content collections for organized content management.
- **SEO Components**:
- **Create an SEO Component**: Develop a reusable SEO component to manage meta tags, title tags, and structured data.
- Use frontmatter or component props to pass SEO-related data.
- **Data Fetching**:
- Fetch data at build time using `Astro.fetchContent` or `getStaticPaths()`.
- Use `Astro.glob()` for importing multiple files.
- Implement proper error handling for data fetching operations.
---
# Performance Optimization
- **Minimal JavaScript**: Reduce client-side JavaScript to essential functionality.
- **Partial Hydration**: Use Astro client directives for interactive components:
- `client:load` for components that need immediate hydration.
- `client:idle` for non-critical components.
- `client:visible` for components that hydrate upon visibility.
- **Asset Optimization**:
- Optimize images using Astro image integration (`@astrojs/image`).
- **Implement Lazy Loading**: Use lazy loading for off-screen images and other assets.
- **Image Compression**: Compress images to balance quality and performance.
- **Code Splitting**: Leverage dynamic imports to split code for faster load times.
- **Caching**: Use HTTP caching headers for static assets.
- **Optimize Builds**:
- Minify HTML, CSS, and JavaScript in production builds.
- **Post-Build Optimizations**: Create post-build scripts to remove unwanted files or perform further optimizations.
- **Page Speed Optimization**:
- Regularly audit and improve page load times.
- Use tools like Google PageSpeed Insights for recommendations.
---
# SEO Best Practices
- **High-Quality Content**:
- Focus on creating valuable, informative, and relevant content.
- Perform keyword research to identify relevant search terms.
- **Technical SEO**:
- Ensure clean and well-structured code.
- **Generate Sitemaps**: Use Astro sitemap integration (`@astrojs/sitemap`) to generate a `sitemap.xml`.
- **Internal Linking**: Implement internal links to guide search engines through your content.
- **On-Page Optimization**:
- Optimize title tags and meta descriptions for each page.
- Use heading tags (`<h1>` to `<h6>`) appropriately to structure content.
- Use frontmatter or props to manage SEO metadata.
- **Image Optimization**:
- Use descriptive `alt` text for images to improve accessibility and SEO.
- Optimize image file sizes and formats.
- **Structured Data Markup**:
- Utilize schema.org markup to provide rich information to search engines.
- Implement structured data using JSON-LD in your SEO component.
- **Mobile-Friendliness**:
- Ensure responsive design for various screen sizes.
- Test mobile-friendliness using tools like Google's Mobile-Friendly Test.
- **Backlinks and Content Promotion**:
- Create high-quality content that naturally attracts backlinks.
- Promote content through appropriate channels to enhance visibility.
- **Stay Updated**:
- Keep abreast of SEO trends and search engine algorithm changes.
---
# UI and Styling with Tailwind CSS
- **Integration**:
- Set up Tailwind CSS using the `@astrojs/tailwind` integration.
- Configure Tailwind in `tailwind.config.cjs`.
- **Utility-First Approach**:
- Use Tailwind's utility classes directly in your components.
- Avoid custom CSS when Tailwind utilities suffice.
- **Responsive Design**:
- Utilize Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`).
- Ensure your design adapts to various devices and screen sizes.
- **Custom Themes**:
- Extend Tailwind's default theme when necessary.
- Keep theme customizations minimal and consistent.
- **Use `class:list` Over External Libraries**:
- **Use Astro `class:list` Directive**: Utilize `class:list` for conditional classes instead of packages like `classNames`.
- **Example**:
```astro
<div class:list={{ active: isActive, disabled: isDisabled }}>...</div>
```
---
# Build and Deployment
- **Environment Variables**:
- Use environment variables for configuration.
- Access variables securely in Astro using `import.meta.env`.
- **Static Hosting**:
- Deploy to platforms like Netlify, Vercel, GitHub Pages, or Cloudflare Pages.
- Ensure your build command is correctly set (usually `astro build`).
- **Continuous Integration/Continuous Deployment (CI/CD)**:
- Set up automated builds and tests in your CI/CD pipeline.
- Use deployment previews for testing before going live.
- **Optimizations**:
- Minify and compress assets in production builds.
- Implement prefetching and prerendering where appropriate.
- **Robots.txt and Sitemap**:
- **Generate a `robots.txt` File**: Inform crawlers how to navigate your site.
- Use Astro sitemap integration to generate a `sitemap.xml`.
---
# Testing and Accessibility
- **Testing**:
- Write unit tests for critical functions and components.
- Use end-to-end testing tools like Cypress for user flow testing.
- Implement integration tests for complex interactions.
- **Accessibility (A11y)**:
- Use semantic HTML elements.
- Provide alternative text for images.
- Ensure keyboard navigability.
- Implement ARIA attributes where necessary.
- **Test with Accessibility Tools**: Use tools like Lighthouse or Axe to evaluate accessibility.
---
# Key Conventions and Best Practices
1. **Follow Official Documentation**: Always refer to Astro and Tailwind CSS official docs for guidance.
2. **Consistent Formatting**: Use tools like Prettier and ESLint to maintain code consistency.
3. **Version Control**: Commit early and often with clear commit messages.
4. **Code Reviews**: Encourage peer reviews to maintain code quality.
5. **Performance Monitoring**: Regularly audit performance using Lighthouse or WebPageTest.
6. **Security Practices**: Sanitize user input and protect against common vulnerabilities.
7. **Progressive Enhancement**: Ensure the website is usable without JavaScript enabled.
8. **Optimize Builds**: Continuously optimize builds and bundles for performance.
9. **Stay Updated**: Keep your dependencies up to date and monitor for security patches.
---
# Additional Resources
- **Astro Documentation**: [https://docs.astro.build](https://docs.astro.build)
- **Tailwind CSS Documentation**: [https://tailwindcss.com/docs](https://tailwindcss.com/docs)
- **Astro SEO Guide**: [Astro SEO Best Practices](https://docs.astro.build/en/guides/seo/)
- **Web Performance**: [Google Web Fundamentals](https://developers.google.com/web/fundamentals/performance)
- **Accessibility Guidelines**: [WCAG 2.1 Standards](https://www.w3.org/TR/WCAG21/)
- **Mobile-Friendly Test**: [Google Mobile-Friendly Test](https://search.google.com/test/mobile-friendly)