building-with-medusa

Name: building-with-medusa
Author: medusajs

202stars24forks

How to install building-with-medusa?

medusajs/medusa-agent-skills/building-with-medusa

$npx -y skills add medusajs/medusa-agent-skills --skill building-with-medusa

Installs into the current project.

Summary

Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains archi

Files · 1

View on GitHub

SKILL.md

1	# Medusa Backend Development
2
3	Comprehensive backend development guide for Medusa applications. Contains patterns across 6 categories covering architecture, type safety, business logic placement, and common pitfalls.
4
5	## When to Apply
6
7	Load this skill for ANY backend development task, including:
8	- Creating or modifying custom modules and data models
9	- Implementing workflows for mutations
10	- Building API routes (store or admin)
11	- Defining module links between entities
12	- Writing business logic or validation
13	- Querying data across modules
14	- Implementing authentication/authorization
15
16	Also load these skills when:
17	- building-admin-dashboard-customizations: Building admin UI (widgets, pages, forms)
18	- building-storefronts: Calling backend API routes from storefronts (SDK integration)
19
20	## CRITICAL: Load Reference Files When Needed
21
22	The quick reference below is NOT sufficient for implementation. You MUST load relevant reference files before writing code for that component.
23
24	Load these references based on what you're implementing:
25
26	- Creating a module? → MUST load `reference/custom-modules.md` first
27	- Creating workflows? → MUST load `reference/workflows.md` first
28	- Creating API routes? → MUST load `reference/api-routes.md` first
29	- Creating module links? → MUST load `reference/module-links.md` first
30	- Querying data? → MUST load `reference/querying-data.md` first
31	- Adding authentication? → MUST load `reference/authentication.md` first
32
33	Minimum requirement: Load at least 1-2 reference files relevant to your specific task before implementing.
34
35	## Critical Architecture Pattern
36
37	ALWAYS follow this flow - never bypass layers:
38
39	```
40	Module (data models + CRUD operations)
41	↓ used by
42	Workflow (business logic + mutations with rollback)
43	↓ executed by
44	API Route (HTTP interface, validation middleware)
45	↓ called by
46	Frontend (admin dashboard/storefront via SDK)
47	```
48
49	Key conventions:
50	- Only GET, POST, DELETE methods (never PUT/PATCH)
51	- Workflows are required for ALL mutations
52	- Business logic belongs in workflow steps, NOT routes
53	- Query with `query.graph()` for cross-module data retrieval
54	- Query with `query.index()` (Index Module) for filtering across separate modules with links
55	- Module links maintain isolation between modules
56
57	## Rule Categories by Priority
58
59	\| Priority \| Category \| Impact \| Prefix \|
60	\|----------\|----------\|--------\|--------\|
61	\| 1 \| Architecture Violations \| CRITICAL \| `arch-` \|
62	\| 2 \| Type Safety \| CRITICAL \| `type-` \|
63	\| 3 \| Business Logic Placement \| HIGH \| `logic-` \|
64	\| 4 \| Import & Code Organization \| HIGH \| `import-` \|
65	\| 5 \| Data Access Patterns \| MEDIUM (includes CRITICAL price rule) \| `data-` \|
66	\| 6 \| File Organization \| MEDIUM \| `file-` \|
67
68	## Quick Reference
69
70	### 1. Architecture Violations (CRITICAL)
71
72	- `arch-workflow-required` - Use workflows for ALL mutations, never call module services from routes
73	- `arch-layer-bypass` - Never bypass layers (route → service without workflow)
74	- `arch-http-methods` - Use only GET, POST, DELETE (never PUT/PATCH)
75	- `arch-module-isolation` - Use module links, not direct cross-module service calls
76	- `arch-query-config-fields` - Don't set explicit `fields` when using `req.queryConfig`
77
78	### 2. Type Safety (CRITICAL)
79
80	- `type-request-schema` - Pass Zod inferred type to `MedusaRequest<T>` when using `req.validatedBody`
81	- `type-authenticated-request` - Use `AuthenticatedMedusaRequest` for protected routes (not `MedusaRequest`)
82	- `type-export-schema` - Export both Zod schema AND inferred type from middlewares
83	- `type-linkable-auto` - Never add `.linkable()` to data models (automatically added)
84	- `type-module-name-camelcase` - Module names MUST be camelCase, never use dashes (causes runtime errors)
85
86	### 3. Business Logic Placement (HIGH)
87
88	- `logic-workflow-validation` - Put business validation in workflow steps, not API routes
89	- `logic-ownership-checks` - Validate ownership/permissions in workflows, not routes
90	- `logic-module-service` - Keep modules simple (CRUD only), put logic in workflows
91
92	### 4. Import & Code Organization (HIGH)
93
94	- `import-top-level` - Import workflows/modules at file top, never use `await import()` in route body
95	- `import-static-only` - Use static imports for all dependencies
96	- `import-no-dynamic-routes` - Dynamic imports add overhead and break type checking
97
98	### 5. Data Access Patterns (MEDIUM)
99
100	- `data-price-format` - CRITICAL: Prices are stored as-is in Medusa (49.99 stored as 49.99, NOT in cents). Never multiply by 100 when saving or divide by 100 when displaying
101	- `data-query-method` - Use `

People who liked this also viewed

6 picks

Type

building-with-medusa

202stars24forks

View on GitHub

How to install building-with-medusa?

medusajs/medusa-agent-skills/building-with-medusa

$npx -y skills add medusajs/medusa-agent-skills --skill building-with-medusa

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Medusa Backend Development
2
3	Comprehensive backend development guide for Medusa applications. Contains patterns across 6 categories covering architecture, type safety, business logic placement, and common pitfalls.
4
5	## When to Apply
6
7	Load this skill for ANY backend development task, including:
8	- Creating or modifying custom modules and data models
9	- Implementing workflows for mutations
10	- Building API routes (store or admin)
11	- Defining module links between entities
12	- Writing business logic or validation
13	- Querying data across modules
14	- Implementing authentication/authorization
15
16	Also load these skills when:
17	- building-admin-dashboard-customizations: Building admin UI (widgets, pages, forms)
18	- building-storefronts: Calling backend API routes from storefronts (SDK integration)
19
20	## CRITICAL: Load Reference Files When Needed
21
22	The quick reference below is NOT sufficient for implementation. You MUST load relevant reference files before writing code for that component.
23
24	Load these references based on what you're implementing:
25
26	- Creating a module? → MUST load `reference/custom-modules.md` first
27	- Creating workflows? → MUST load `reference/workflows.md` first
28	- Creating API routes? → MUST load `reference/api-routes.md` first
29	- Creating module links? → MUST load `reference/module-links.md` first
30	- Querying data? → MUST load `reference/querying-data.md` first
31	- Adding authentication? → MUST load `reference/authentication.md` first
32
33	Minimum requirement: Load at least 1-2 reference files relevant to your specific task before implementing.
34
35	## Critical Architecture Pattern
36
37	ALWAYS follow this flow - never bypass layers:
38
39	```
40	Module (data models + CRUD operations)
41	↓ used by
42	Workflow (business logic + mutations with rollback)
43	↓ executed by
44	API Route (HTTP interface, validation middleware)
45	↓ called by
46	Frontend (admin dashboard/storefront via SDK)
47	```
48
49	Key conventions:
50	- Only GET, POST, DELETE methods (never PUT/PATCH)
51	- Workflows are required for ALL mutations
52	- Business logic belongs in workflow steps, NOT routes
53	- Query with `query.graph()` for cross-module data retrieval
54	- Query with `query.index()` (Index Module) for filtering across separate modules with links
55	- Module links maintain isolation between modules
56
57	## Rule Categories by Priority
58
59	\| Priority \| Category \| Impact \| Prefix \|
60	\|----------\|----------\|--------\|--------\|
61	\| 1 \| Architecture Violations \| CRITICAL \| `arch-` \|
62	\| 2 \| Type Safety \| CRITICAL \| `type-` \|
63	\| 3 \| Business Logic Placement \| HIGH \| `logic-` \|
64	\| 4 \| Import & Code Organization \| HIGH \| `import-` \|
65	\| 5 \| Data Access Patterns \| MEDIUM (includes CRITICAL price rule) \| `data-` \|
66	\| 6 \| File Organization \| MEDIUM \| `file-` \|
67
68	## Quick Reference
69
70	### 1. Architecture Violations (CRITICAL)
71
72	- `arch-workflow-required` - Use workflows for ALL mutations, never call module services from routes
73	- `arch-layer-bypass` - Never bypass layers (route → service without workflow)
74	- `arch-http-methods` - Use only GET, POST, DELETE (never PUT/PATCH)
75	- `arch-module-isolation` - Use module links, not direct cross-module service calls
76	- `arch-query-config-fields` - Don't set explicit `fields` when using `req.queryConfig`
77
78	### 2. Type Safety (CRITICAL)
79
80	- `type-request-schema` - Pass Zod inferred type to `MedusaRequest<T>` when using `req.validatedBody`
81	- `type-authenticated-request` - Use `AuthenticatedMedusaRequest` for protected routes (not `MedusaRequest`)
82	- `type-export-schema` - Export both Zod schema AND inferred type from middlewares
83	- `type-linkable-auto` - Never add `.linkable()` to data models (automatically added)
84	- `type-module-name-camelcase` - Module names MUST be camelCase, never use dashes (causes runtime errors)
85
86	### 3. Business Logic Placement (HIGH)
87
88	- `logic-workflow-validation` - Put business validation in workflow steps, not API routes
89	- `logic-ownership-checks` - Validate ownership/permissions in workflows, not routes
90	- `logic-module-service` - Keep modules simple (CRUD only), put logic in workflows
91
92	### 4. Import & Code Organization (HIGH)
93
94	- `import-top-level` - Import workflows/modules at file top, never use `await import()` in route body
95	- `import-static-only` - Use static imports for all dependencies
96	- `import-no-dynamic-routes` - Dynamic imports add overhead and break type checking
97
98	### 5. Data Access Patterns (MEDIUM)
99
100	- `data-price-format` - CRITICAL: Prices are stored as-is in Medusa (49.99 stored as 49.99, NOT in cents). Never multiply by 100 when saving or divide by 100 when displaying
101	- `data-query-method` - Use `

People who liked this also viewed

6 picks

Type