building-storefronts

Name: building-storefronts
Author: medusajs

202stars24forks

How to install building-storefronts?

medusajs/medusa-agent-skills/building-storefronts

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

Installs into the current project.

Summary

Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK

Files · 1

View on GitHub

SKILL.md

1	# Medusa Storefront Development
2
3	Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
4
5	## When to Apply
6
7	Load this skill for ANY storefront development task, including:
8	- Calling custom Medusa API routes from the storefront
9	- Integrating Medusa SDK in frontend applications
10	- Using React Query for data fetching
11	- Implementing mutations with optimistic updates
12	- Error handling and cache invalidation
13
14	Also load building-with-medusa when: Building the backend API routes that the storefront calls
15
16	## CRITICAL: Load Reference Files When Needed
17
18	The quick reference below is NOT sufficient for implementation. You MUST load the reference file before writing storefront integration code.
19
20	Load this reference when implementing storefront features:
21
22	- Calling API routes? → MUST load `references/frontend-integration.md` first
23	- Using SDK? → MUST load `references/frontend-integration.md` first
24	- Implementing React Query? → MUST load `references/frontend-integration.md` first
25
26	## Rule Categories by Priority
27
28	\| Priority \| Category \| Impact \| Prefix \|
29	\|----------\|----------\|--------\|--------\|
30	\| 1 \| SDK Usage \| CRITICAL \| `sdk-` \|
31	\| 2 \| React Query Patterns \| HIGH \| `query-` \|
32	\| 3 \| Data Display \| HIGH (includes CRITICAL price rule) \| `display-` \|
33	\| 4 \| Error Handling \| MEDIUM \| `error-` \|
34
35	## Quick Reference
36
37	### 1. SDK Usage (CRITICAL)
38
39	- `sdk-always-use` - ALWAYS use the Medusa JS SDK for ALL API requests - NEVER use regular fetch()
40	- `sdk-existing-methods` - For built-in endpoints, use existing SDK methods (`sdk.store.product.list()`, `sdk.admin.order.retrieve()`)
41	- `sdk-client-fetch` - For custom API routes, use `sdk.client.fetch()`
42	- `sdk-required-headers` - SDK automatically adds required headers (publishable API key for store, auth for admin) - regular fetch() missing these headers causes errors
43	- `sdk-no-json-stringify` - NEVER use JSON.stringify() on body - SDK handles serialization automatically
44	- `sdk-plain-objects` - Pass plain JavaScript objects to body, not strings
45	- `sdk-locate-first` - Always locate where SDK is instantiated in the project before using it
46
47	### 2. React Query Patterns (HIGH)
48
49	- `query-use-query` - Use `useQuery` for GET requests (data fetching)
50	- `query-use-mutation` - Use `useMutation` for POST/DELETE requests (mutations)
51	- `query-invalidate` - Invalidate queries in `onSuccess` to refresh data after mutations
52	- `query-keys-hierarchical` - Structure query keys hierarchically for effective cache management
53	- `query-loading-states` - Always handle `isLoading`, `isPending`, `isError` states
54
55	### 3. Data Display (HIGH)
56
57	- `display-price-format` - CRITICAL: Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100
58
59	### 4. Error Handling (MEDIUM)
60
61	- `error-on-error` - Implement `onError` callback in mutations to handle failures
62	- `error-display` - Show error messages to users when mutations fail
63	- `error-rollback` - Use optimistic updates with rollback on error for better UX
64
65	## Critical SDK Pattern
66
67	ALWAYS pass plain objects to the SDK - NEVER use JSON.stringify():
68
69	```typescript
70	// ✅ CORRECT - Plain object
71	await sdk.client.fetch("/store/reviews", {
72	method: "POST",
73	body: {
74	product_id: "prod_123",
75	rating: 5,
76	}
77	})
78
79	// ❌ WRONG - JSON.stringify breaks the request
80	await sdk.client.fetch("/store/reviews", {
81	method: "POST",
82	body: JSON.stringify({ // ❌ DON'T DO THIS!
83	product_id: "prod_123",
84	rating: 5,
85	})
86	})
87	```
88
89	Why this matters:
90	- The SDK handles JSON serialization automatically
91	- Using JSON.stringify() will double-serialize and break the request
92	- The server won't be able to parse the body
93
94	## Common Mistakes Checklist
95
96	Before implementing, verify you're NOT doing these:
97
98	SDK Usage:
99	- [ ] Using regular fetch() instead of the Medusa JS SDK (causes missing header errors)
100	- [ ] Not using existing SDK methods for built-in endpoints (e.g., using sdk.client.fetch("/store/products") instead of sdk.store.product.list())
101	- [ ] Using JSON.stringify() on the body parameter
102	- [ ] Manually setting Content-Type headers (SDK adds them)
103	- [ ] Hardcoding SDK import paths (locate in project first)
104	- [ ] Not using sdk.client.fetch() for custom routes
105
106	React Query:
107	- [ ] Not invalidating queries after mutations
108	- [ ] Using flat query keys instead of hierarchical
109	- [ ] Not handling loading and error states
110	- [ ] Forgetting to disable buttons during mutations (isPending)
111
112	Data Display:
113	- [ ] **CRITICA

People who liked this also viewed

6 picks

Type

building-storefronts

202stars24forks

View on GitHub

How to install building-storefronts?

medusajs/medusa-agent-skills/building-storefronts

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Medusa Storefront Development
2
3	Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
4
5	## When to Apply
6
7	Load this skill for ANY storefront development task, including:
8	- Calling custom Medusa API routes from the storefront
9	- Integrating Medusa SDK in frontend applications
10	- Using React Query for data fetching
11	- Implementing mutations with optimistic updates
12	- Error handling and cache invalidation
13
14	Also load building-with-medusa when: Building the backend API routes that the storefront calls
15
16	## CRITICAL: Load Reference Files When Needed
17
18	The quick reference below is NOT sufficient for implementation. You MUST load the reference file before writing storefront integration code.
19
20	Load this reference when implementing storefront features:
21
22	- Calling API routes? → MUST load `references/frontend-integration.md` first
23	- Using SDK? → MUST load `references/frontend-integration.md` first
24	- Implementing React Query? → MUST load `references/frontend-integration.md` first
25
26	## Rule Categories by Priority
27
28	\| Priority \| Category \| Impact \| Prefix \|
29	\|----------\|----------\|--------\|--------\|
30	\| 1 \| SDK Usage \| CRITICAL \| `sdk-` \|
31	\| 2 \| React Query Patterns \| HIGH \| `query-` \|
32	\| 3 \| Data Display \| HIGH (includes CRITICAL price rule) \| `display-` \|
33	\| 4 \| Error Handling \| MEDIUM \| `error-` \|
34
35	## Quick Reference
36
37	### 1. SDK Usage (CRITICAL)
38
39	- `sdk-always-use` - ALWAYS use the Medusa JS SDK for ALL API requests - NEVER use regular fetch()
40	- `sdk-existing-methods` - For built-in endpoints, use existing SDK methods (`sdk.store.product.list()`, `sdk.admin.order.retrieve()`)
41	- `sdk-client-fetch` - For custom API routes, use `sdk.client.fetch()`
42	- `sdk-required-headers` - SDK automatically adds required headers (publishable API key for store, auth for admin) - regular fetch() missing these headers causes errors
43	- `sdk-no-json-stringify` - NEVER use JSON.stringify() on body - SDK handles serialization automatically
44	- `sdk-plain-objects` - Pass plain JavaScript objects to body, not strings
45	- `sdk-locate-first` - Always locate where SDK is instantiated in the project before using it
46
47	### 2. React Query Patterns (HIGH)
48
49	- `query-use-query` - Use `useQuery` for GET requests (data fetching)
50	- `query-use-mutation` - Use `useMutation` for POST/DELETE requests (mutations)
51	- `query-invalidate` - Invalidate queries in `onSuccess` to refresh data after mutations
52	- `query-keys-hierarchical` - Structure query keys hierarchically for effective cache management
53	- `query-loading-states` - Always handle `isLoading`, `isPending`, `isError` states
54
55	### 3. Data Display (HIGH)
56
57	- `display-price-format` - CRITICAL: Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100
58
59	### 4. Error Handling (MEDIUM)
60
61	- `error-on-error` - Implement `onError` callback in mutations to handle failures
62	- `error-display` - Show error messages to users when mutations fail
63	- `error-rollback` - Use optimistic updates with rollback on error for better UX
64
65	## Critical SDK Pattern
66
67	ALWAYS pass plain objects to the SDK - NEVER use JSON.stringify():
68
69	```typescript
70	// ✅ CORRECT - Plain object
71	await sdk.client.fetch("/store/reviews", {
72	method: "POST",
73	body: {
74	product_id: "prod_123",
75	rating: 5,
76	}
77	})
78
79	// ❌ WRONG - JSON.stringify breaks the request
80	await sdk.client.fetch("/store/reviews", {
81	method: "POST",
82	body: JSON.stringify({ // ❌ DON'T DO THIS!
83	product_id: "prod_123",
84	rating: 5,
85	})
86	})
87	```
88
89	Why this matters:
90	- The SDK handles JSON serialization automatically
91	- Using JSON.stringify() will double-serialize and break the request
92	- The server won't be able to parse the body
93
94	## Common Mistakes Checklist
95
96	Before implementing, verify you're NOT doing these:
97
98	SDK Usage:
99	- [ ] Using regular fetch() instead of the Medusa JS SDK (causes missing header errors)
100	- [ ] Not using existing SDK methods for built-in endpoints (e.g., using sdk.client.fetch("/store/products") instead of sdk.store.product.list())
101	- [ ] Using JSON.stringify() on the body parameter
102	- [ ] Manually setting Content-Type headers (SDK adds them)
103	- [ ] Hardcoding SDK import paths (locate in project first)
104	- [ ] Not using sdk.client.fetch() for custom routes
105
106	React Query:
107	- [ ] Not invalidating queries after mutations
108	- [ ] Using flat query keys instead of hierarchical
109	- [ ] Not handling loading and error states
110	- [ ] Forgetting to disable buttons during mutations (isPending)
111
112	Data Display:
113	- [ ] **CRITICA

People who liked this also viewed

6 picks

Type