Skip to content

Commit 333ce96

Browse files
jaruesinkjaruesink
authored
Merge pull request #66 from lambda-curry/codegen/lc-239-create-comprehensive-cursor-rules-for-medusa-development
feat: Add comprehensive Cursor rules for Medusa development
2 parents 72e47cf + 2c9cd64 commit 333ce96

9 files changed

+2228
-0
lines changed

‎.cursor/README.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Cursor Rules for Medusa Development
2+
3+
This directory contains comprehensive Cursor rules designed to enhance AI-assisted development for Medusa v2 applications. These rules provide context-aware suggestions and best practices for building scalable e-commerce applications.
4+
5+
## 📁 Rule Files Overview
6+
7+
### Core Development Rules
8+
9+
#### `medusa-development.mdc`
10+
**Primary rule file for Medusa v2 backend development**
11+
- Medusa v2 architectural patterns and conventions
12+
- Module, service, and API route development
13+
- Database models and repository patterns
14+
- Workflow and subscriber implementations
15+
- Security and validation best practices
16+
- Performance optimization techniques
17+
18+
#### Remix Storefront Rules (Split for Better Organization)
19+
20+
**`remix-storefront-routing.mdc`**
21+
- React Router v7 patterns and conventions
22+
- Route structure and loader/action patterns
23+
- Medusa SDK integration
24+
- Form handling with @lambdacurry/forms
25+
- API integration patterns
26+
27+
**`remix-storefront-components.mdc`**
28+
- Component patterns and architecture
29+
- Styling with Tailwind CSS
30+
- Responsive design principles
31+
- Reusable component patterns
32+
33+
**`remix-storefront-optimization.mdc`**
34+
- Performance optimization and caching strategies
35+
- SEO optimization and meta tag management
36+
- Error handling and accessibility
37+
- Testing patterns for components
38+
39+
#### `typescript-patterns.mdc`
40+
**Advanced TypeScript patterns and best practices**
41+
- Type definitions and interface design
42+
- Generic types and utility types
43+
- Error handling patterns
44+
- Async programming patterns
45+
- Functional programming concepts
46+
- Testing type definitions
47+
48+
#### Testing Rules (Split by Testing Type)
49+
50+
**`testing-patterns-unit.mdc`**
51+
- Unit testing for services and components
52+
- Service layer testing patterns
53+
- React component testing
54+
- Hook testing patterns
55+
56+
**`testing-patterns-integration.mdc`**
57+
- Integration testing for APIs and databases
58+
- Workflow testing
59+
- Database integration patterns
60+
61+
**`testing-patterns-e2e.mdc`**
62+
- End-to-end testing with Playwright
63+
- Storefront user journey testing
64+
- Test utilities and factories
65+
- Mocking strategies and best practices
66+
67+
#### `remix-hook-form-migration.mdc`
68+
**Migration guide from remix-validated-form to @lambdacurry/forms**
69+
- Form validation patterns (Yup to Zod)
70+
- Component migration examples
71+
- Error handling updates
72+
- Response handling patterns
73+
74+
## 🚀 Getting Started
75+
76+
### Prerequisites
77+
- Cursor IDE installed
78+
- Medusa v2 project setup
79+
- TypeScript configuration
80+
81+
### Activation
82+
These rules are automatically applied based on file patterns:
83+
- `.mdc` files in `.cursor/rules/` are automatically loaded
84+
- Rules apply to specific file patterns defined in each rule's `globs` section
85+
- `alwaysApply: true` ensures rules are active for matching files
86+
87+
### File Pattern Targeting
88+
89+
| Rule File | Target Files |
90+
|-----------|-------------|
91+
| `medusa-development.mdc` | `apps/medusa/**/*.ts`, `apps/medusa/**/*.tsx` |
92+
| `remix-storefront-routing.mdc` | `apps/storefront/**/*.ts`, `apps/storefront/**/*.tsx` |
93+
| `remix-storefront-components.mdc` | `apps/storefront/**/*.ts`, `apps/storefront/**/*.tsx` |
94+
| `remix-storefront-optimization.mdc` | `apps/storefront/**/*.ts`, `apps/storefront/**/*.tsx` |
95+
| `typescript-patterns.mdc` | `**/*.ts`, `**/*.tsx` |
96+
| `testing-patterns-unit.mdc` | `**/*.test.ts`, `**/*.spec.ts`, `**/__tests__/**/*` |
97+
| `testing-patterns-integration.mdc` | `**/*.test.ts`, `**/*.spec.ts`, `**/__tests__/**/*` |
98+
| `testing-patterns-e2e.mdc` | `**/*.test.ts`, `**/*.spec.ts`, `**/__tests__/**/*` |
99+
| `remix-hook-form-migration.mdc` | All TypeScript files (migration context) |
100+
101+
## 🎯 Key Features
102+
103+
### Medusa v2 Specific Guidance
104+
- **Module Development**: Patterns for creating custom Medusa modules
105+
- **Service Layer**: Dependency injection and business logic patterns
106+
- **API Routes**: RESTful endpoint development for admin and store APIs
107+
- **Database Integration**: Model definitions and repository patterns
108+
- **Event-Driven Architecture**: Subscribers and workflow implementations
109+
110+
### React/Remix Best Practices
111+
- **Component Architecture**: Reusable component patterns
112+
- **State Management**: Cart management with Zustand
113+
- **Form Handling**: Modern form patterns with react-hook-form
114+
- **Performance**: Code splitting, image optimization, caching strategies
115+
- **SEO**: Meta tags, structured data, accessibility
116+
117+
### TypeScript Excellence
118+
- **Type Safety**: Advanced type patterns and utility types
119+
- **Error Handling**: Result patterns and custom error types
120+
- **Async Patterns**: Promise utilities and async iterators
121+
- **Testing**: Type-safe testing patterns and mock utilities
122+
123+
## 🛠️ Usage Examples
124+
125+
### Creating a New Medusa Service
126+
When creating a new service file in `apps/medusa/src/services/`, Cursor will suggest:
127+
128+
```typescript
129+
import { MedusaService } from "@medusajs/framework/utils"
130+
131+
class MyService extends MedusaService({
132+
MyModel,
133+
}) {
134+
async create(data: CreateMyEntityInput): Promise<MyEntity> {
135+
return await this.myModelRepository_.create(data)
136+
}
137+
}
138+
```
139+
140+
### Building React Components
141+
When working in `apps/storefront/app/components/`, Cursor will suggest:
142+
143+
```typescript
144+
interface ProductCardProps {
145+
product: Product
146+
className?: string
147+
}
148+
149+
export function ProductCard({ product, className }: ProductCardProps) {
150+
// Component implementation with proper TypeScript and accessibility
151+
}
152+
```
153+
154+
### Writing Tests
155+
When creating test files, Cursor will suggest proper testing patterns:
156+
157+
```typescript
158+
describe("UserService", () => {
159+
let container: MedusaContainer
160+
let userService: UserService
161+
162+
beforeEach(() => {
163+
container = createMedusaContainer()
164+
userService = container.resolve("userService")
165+
})
166+
167+
it("should create a new user with valid data", async () => {
168+
// Arrange, Act, Assert pattern
169+
})
170+
}
171+
```
172+
173+
## 📚 Best Practices Enforced
174+
175+
### Code Quality
176+
- ✅ Strict TypeScript usage
177+
- ✅ Proper error handling
178+
- ✅ Input validation with Zod
179+
- ✅ Comprehensive testing
180+
- ✅ Performance optimization
181+
182+
### Architecture
183+
- ✅ Modular design patterns
184+
- ✅ Dependency injection
185+
- ✅ Event-driven architecture
186+
- ✅ RESTful API design
187+
- ✅ Database best practices
188+
189+
### Security
190+
- ✅ Input sanitization
191+
- ✅ Authentication patterns
192+
- ✅ CORS configuration
193+
- ✅ Environment variable management
194+
- ✅ SQL injection prevention
195+
196+
## 🔧 Customization
197+
198+
### Adding Custom Rules
199+
1. Create a new `.mdc` file in `.cursor/rules/`
200+
2. Define the rule metadata:
201+
```yaml
202+
---
203+
description: Your custom rule description
204+
globs:
205+
- "path/to/target/files/**/*.ts"
206+
alwaysApply: true
207+
---
208+
```
209+
3. Add your custom guidance and patterns
210+
211+
### Modifying Existing Rules
212+
- Edit the relevant `.mdc` file
213+
- Rules are automatically reloaded by Cursor
214+
- Test changes with relevant file types
215+
216+
## 🎨 Integration with Development Workflow
217+
218+
### With Medusa CLI
219+
These rules complement Medusa CLI commands:
220+
- `medusa develop` - Rules provide guidance during development
221+
- `medusa build` - Rules ensure production-ready code patterns
222+
- `medusa db:migrate` - Rules suggest proper migration patterns
223+
224+
### With Package Scripts
225+
Rules enhance development with existing scripts:
226+
- `yarn dev` - Real-time guidance during development
227+
- `yarn build` - Production build optimization suggestions
228+
- `yarn test` - Testing pattern recommendations
229+
- `yarn typecheck` - TypeScript best practice enforcement
230+
231+
## 📖 Learning Resources
232+
233+
### Official Documentation
234+
- [Medusa v2 Documentation](https://docs.medusajs.com/)
235+
- [React Router v7 Documentation](https://reactrouter.com/)
236+
- [Cursor Rules Documentation](https://docs.cursor.com/context/rules)
237+
238+
### Code Examples
239+
Each rule file contains extensive code examples demonstrating:
240+
- Common patterns and anti-patterns
241+
- Best practice implementations
242+
- Error handling strategies
243+
- Performance optimization techniques
244+
245+
## 🤝 Contributing
246+
247+
### Improving Rules
248+
1. Identify areas for improvement in existing rules
249+
2. Add new patterns based on project experience
250+
3. Update examples with real-world scenarios
251+
4. Ensure rules stay current with framework updates
252+
253+
### Feedback
254+
- Report issues with rule suggestions
255+
- Suggest new patterns or improvements
256+
- Share successful implementations
257+
258+
## 📝 Maintenance
259+
260+
### Regular Updates
261+
- Keep rules synchronized with Medusa v2 updates
262+
- Update React Router patterns as the framework evolves
263+
- Refresh TypeScript patterns with new language features
264+
- Maintain testing patterns with latest testing library updates
265+
266+
### Version Compatibility
267+
- Rules are designed for Medusa v2.7.0+
268+
- React Router v7 compatibility
269+
- TypeScript 5.6+ features
270+
- Node.js 20+ patterns
271+
272+
---
273+
274+
These Cursor rules are designed to accelerate development while maintaining code quality and consistency across the Medusa application. They serve as an intelligent coding assistant, providing contextual guidance based on the specific file and framework being used.

0 commit comments

Comments
 (0)