medusa — Cursor rule: building Medusa apps
A Cursor rule that keeps Medusa code on one pattern: workflows, data models, services and admin customizations.
.cursor/rules/medusa.mdcWhat medusa does
The rule lives in Cursor and applies to **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx. Auto-apply is off, so it kicks in on matching paths rather than on every file.
Four areas are covered. General: throw MedusaError for failures, fetch data through Query, skip type aliases on imports. Workflows: define them with @medusajs/framework/workflows-sdk, give each workflow its own step, use transform for data changes and when for conditions, call steps without await, and keep the workflow function non-async. Data models come from the model utility in @medusajs/framework/utils — camelCase variables, snake case fields, a single id marked with .primaryKey() while other identifiers stay text. Services that own models extend MedusaService and expose async methods. Admin requests go through the JS SDK, styling through TailwindCSS.
This assumes Medusa is already in the project and its Workflow SDK is the way you build features. Code that defines workflows differently will fight the rule, so expect to edit parts of it to match your existing style.
What it helps with
- define workflows and steps with the Medusa Workflow SDK
- declare data models through the
modelutility - extend
MedusaServicein module services - throw
MedusaErrorinstead of plain errors - route admin requests through the JS SDK
Example prompts for the agent
- Create a workflow for checkout with a step that checks stock
- Define a data model for a warehouse with snake case fields
- Rewrite the module service so it extends
MedusaService
How to install medusa
Manually: put the files in place
.cursor/rules/medusa.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.claude/rules/medusa.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/medusa.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/medusa.mdManually: put the files in place
.clinerules/medusa.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about medusa
How do I install medusa in Cursor?
Create .cursor/rules/medusa.mdc and paste the rule contents into it.
What does the medusa rule do?
It sets Cursor conventions for Medusa code: workflows, data models, services and admin customization.
Which files does the rule cover?
**/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx. Auto-apply is off.
Source text
medusa.mdc · CC0-1.0
--- description: "Medusa rules and best practices. These rules should be used when building applications with Medusa." globs: **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx alwaysApply: false --- You are an expert senior software engineer specializing in modern web development, with deep expertise in TypeScript, Medusa, React.js, and TailwindCSS. # Medusa Rules ## General Rules - Don't use type aliases when importing files. - When throwing errors, always throw `MedusaError`. - Always use Query to retrieve data. ## Workflow Rules - When creating a workflow or step, always use Medusa's Workflow SDK `@medusajs/framework/workflows-sdk` to define it. - When creating a feature in an API route, scheduled job, or subscriber, always create a workflow for it. - When creating a workflow, always create a step for it. - In workflows, use `transform` for any data transformation. - In workflows, use `when` to define conditions. - Don't use `await` when calling steps. - In workflows, don't make the workflow function async. - Don't add typing to compensation function's input. - Only use steps in a workflow. ## Data Model Rules - Use the `model` utility from `@medusajs/framework/utils` to define data models. - Data model variables should be camelCase. Data model names as passed to `model.define` should be snake case. - When adding an `id` field to a data model, always make it a primary key with `.primaryKey()`. - A data model can have one `id` only, other IDs should be `text` instead. - Data model fields should be snake case. ## Service Rules - When creating a service, always make methods async. - If a module has data models, make the service extend `MedusaService`. ## Admin Customization Rules - When sending requests in admin customizations, always use Medusa's JS SDK. - Use TailwindCSS for styling. # Additional Resources - [Medusa Documentation](https://docs.medusajs.com/llms-full.txt)
© PatrickJS · CC0-1.0 · PatrickJS/awesome-cursorrules
