Skip to content

Commit eefda0e

Browse files
shahednassershahednasser
authored
docs: cache in cloud (medusajs#13719)
* docs: cache in cloud * fix build * information updates * add opt out info * fix vale error
1 parent ed71581 commit eefda0e

File tree

5 files changed

+358
-1
lines changed

5 files changed

+358
-1
lines changed

‎www/apps/cloud/app/cache/page.mdx‎

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
import { Prerequisites, Table } from "docs-ui"
2+
3+
export const metadata = {
4+
title: `Medusa Cache`,
5+
}
6+
7+
# {metadata.title}
8+
9+
In this guide, you'll learn about Medusa Cache.
10+
11+
## What is Medusa Cache?
12+
13+
Medusa Cache is a caching layer that improves your application's performance and reduces costs. It's available to all environments and plans out of the box at no additional cost.
14+
15+
Medusa Cache relies on the existing key/value [Redis](../redis/page.mdx) store already provisioned for environments. Each environment has its own isolated cache.
16+
17+
![Diagram showcasing Redis isolation between environments](https://res.cloudinary.com/dza7lstvk/image/upload/v1750230910/Cloud/redis-cloud_llg83c.jpg)
18+
19+
---
20+
21+
## How Does Medusa Cache Work?
22+
23+
### Enabled by Default
24+
25+
Medusa Cache is enabled by default for all environments and plans if your Medusa project is running [Medusa v2.11.0 or later](https://github.com/medusajs/medusa/releases/tag/v2.11.0). No configuration is required to start using caching.
26+
27+
### Cached Data in API Routes
28+
29+
By using Medusa Cache, data is cached across several business-critical APIs to boost performance and throughput. This includes all cart-related operations, where the following data is cached:
30+
31+
- Regions
32+
- Promotion codes
33+
- Variant price sets
34+
- Variants
35+
- Shipping options
36+
- Sales channels
37+
- Customers
38+
39+
### Integrated into Query
40+
41+
{/* Medusa Cache is built on the new [Caching Module](!resources!/infrastructure-modules/caching). The module has been integrated into [Query](!docs!/learn/fundamentals/module-links/query) so that `query.graph` calls can be cached easily. */}
42+
43+
Medusa Cache is built on the new [Caching Module](#). The module has been integrated into [Query](!docs!/learn/fundamentals/module-links/query) so that `query.graph` calls can be cached easily.
44+
45+
You can enable caching for your custom `query.graph` calls by passing a `cache` option. For example:
46+
47+
```ts
48+
const { data: products } = await query.graph({
49+
entity: "product",
50+
fields: ["id", "title", "handle"],
51+
}, {
52+
cache: {
53+
enable: true
54+
}
55+
})
56+
```
57+
58+
This code caches the query result. When the same query is made again, the cached result is returned instead of querying the database.
59+
60+
![Diagram showcasing cache miss and cache hit](https://res.cloudinary.com/dza7lstvk/image/upload/v1759999050/Cloud/medusa-cache-overview_zqpwuo.jpg)
61+
62+
### Automatic Invalidation
63+
64+
By default, data is cached for one hour or until invalidated. Invalidation occurs automatically when related data is created, updated, or deleted.
65+
66+
{/* Learn more about automatic invalidation in the [Caching Module documentation](!resources!/infrastructure-modules/caching/concepts#automatic-cache-invalidation). */}
67+
68+
Learn more about automatic invalidation in the [Caching Module documentation](#).
69+
70+
---
71+
72+
## Performance Benchmark Comparisons
73+
74+
The following benchmark comparisons demonstrate the performance improvements you can expect with Medusa Cache. These were conducted on a Cloud environment with a standard setup.
75+
76+
<Table>
77+
<Table.Header>
78+
<Table.Row>
79+
<Table.HeaderCell className="w-1/2">
80+
Endpoint
81+
</Table.HeaderCell>
82+
<Table.HeaderCell>
83+
Without Medusa Cache (ms)
84+
</Table.HeaderCell>
85+
<Table.HeaderCell>
86+
With Medusa Cache (ms)
87+
</Table.HeaderCell>
88+
<Table.HeaderCell>
89+
Improvement
90+
</Table.HeaderCell>
91+
</Table.Row>
92+
</Table.Header>
93+
<Table.Body>
94+
<Table.Row>
95+
<Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
96+
**Product Operations**
97+
</Table.Cell>
98+
</Table.Row>
99+
<Table.Row>
100+
<Table.Cell>
101+
`GET /store/products`
102+
</Table.Cell>
103+
<Table.Cell>
104+
`354.00`
105+
</Table.Cell>
106+
<Table.Cell>
107+
`83.00`
108+
</Table.Cell>
109+
<Table.Cell>
110+
`~77%`
111+
</Table.Cell>
112+
</Table.Row>
113+
<Table.Row>
114+
<Table.Cell>
115+
`GET /store/product-categories`
116+
</Table.Cell>
117+
<Table.Cell>
118+
`88.00`
119+
</Table.Cell>
120+
<Table.Cell>
121+
`51.00`
122+
</Table.Cell>
123+
<Table.Cell>
124+
`~42%`
125+
</Table.Cell>
126+
</Table.Row>
127+
<Table.Row>
128+
<Table.Cell>
129+
`GET /store/products/:id`
130+
</Table.Cell>
131+
<Table.Cell>
132+
`161.00`
133+
</Table.Cell>
134+
<Table.Cell>
135+
`123.00`
136+
</Table.Cell>
137+
<Table.Cell>
138+
`~24%`
139+
</Table.Cell>
140+
</Table.Row>
141+
<Table.Row>
142+
<Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
143+
**Cart Operations**
144+
</Table.Cell>
145+
</Table.Row>
146+
<Table.Row>
147+
<Table.Cell>
148+
`POST /store/carts/:id/line-items`
149+
</Table.Cell>
150+
<Table.Cell>
151+
`697.00`
152+
</Table.Cell>
153+
<Table.Cell>
154+
`427.00`
155+
</Table.Cell>
156+
<Table.Cell>
157+
`~39%`
158+
</Table.Cell>
159+
</Table.Row>
160+
<Table.Row>
161+
<Table.Cell>
162+
`POST /store/carts/:id/shipping-methods`
163+
</Table.Cell>
164+
<Table.Cell>
165+
`1002.00`
166+
</Table.Cell>
167+
<Table.Cell>
168+
`670.00`
169+
</Table.Cell>
170+
<Table.Cell>
171+
`~33%`
172+
</Table.Cell>
173+
</Table.Row>
174+
<Table.Row>
175+
<Table.Cell>
176+
`POST /store/carts/:id/promotions`
177+
</Table.Cell>
178+
<Table.Cell>
179+
`302.00`
180+
</Table.Cell>
181+
<Table.Cell>
182+
`203.00`
183+
</Table.Cell>
184+
<Table.Cell>
185+
`~33%`
186+
</Table.Cell>
187+
</Table.Row>
188+
<Table.Row>
189+
<Table.Cell>
190+
`GET /store/carts/:id`
191+
</Table.Cell>
192+
<Table.Cell>
193+
`109.00`
194+
</Table.Cell>
195+
<Table.Cell>
196+
`73.00`
197+
</Table.Cell>
198+
<Table.Cell>
199+
`~33%`
200+
</Table.Cell>
201+
</Table.Row>
202+
<Table.Row>
203+
<Table.Cell>
204+
`POST /store/carts/:id`
205+
</Table.Cell>
206+
<Table.Cell>
207+
`909.00`
208+
</Table.Cell>
209+
<Table.Cell>
210+
`656.00`
211+
</Table.Cell>
212+
<Table.Cell>
213+
`~28%`
214+
</Table.Cell>
215+
</Table.Row>
216+
<Table.Row>
217+
<Table.Cell>
218+
`POST /store/carts`
219+
</Table.Cell>
220+
<Table.Cell>
221+
`446.00`
222+
</Table.Cell>
223+
<Table.Cell>
224+
`329.00`
225+
</Table.Cell>
226+
<Table.Cell>
227+
`~26%`
228+
</Table.Cell>
229+
</Table.Row>
230+
<Table.Row>
231+
<Table.Cell>
232+
`POST /store/carts/:id/complete`
233+
</Table.Cell>
234+
<Table.Cell>
235+
`1357.00`
236+
</Table.Cell>
237+
<Table.Cell>
238+
`1018.00`
239+
</Table.Cell>
240+
<Table.Cell>
241+
`~25%`
242+
</Table.Cell>
243+
</Table.Row>
244+
<Table.Row>
245+
<Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
246+
**Order Operations**
247+
</Table.Cell>
248+
</Table.Row>
249+
<Table.Row>
250+
<Table.Cell>
251+
`GET /store/orders/:id`
252+
</Table.Cell>
253+
<Table.Cell>
254+
`119.00`
255+
</Table.Cell>
256+
<Table.Cell>
257+
`81.00`
258+
</Table.Cell>
259+
<Table.Cell>
260+
`~32%`
261+
</Table.Cell>
262+
</Table.Row>
263+
<Table.Row>
264+
<Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
265+
**Other Operations**
266+
</Table.Cell>
267+
</Table.Row>
268+
<Table.Row>
269+
<Table.Cell>
270+
`GET /store/regions`
271+
</Table.Cell>
272+
<Table.Cell>
273+
`89.00`
274+
</Table.Cell>
275+
<Table.Cell>
276+
`51.00`
277+
</Table.Cell>
278+
<Table.Cell>
279+
`~43%`
280+
</Table.Cell>
281+
</Table.Row>
282+
<Table.Row>
283+
<Table.Cell>
284+
`GET /store/shipping-options`
285+
</Table.Cell>
286+
<Table.Cell>
287+
`272.00`
288+
</Table.Cell>
289+
<Table.Cell>
290+
`173.00`
291+
</Table.Cell>
292+
<Table.Cell>
293+
`~36%`
294+
</Table.Cell>
295+
</Table.Row>
296+
<Table.Row>
297+
<Table.Cell>
298+
`POST /store/payment-collections`
299+
</Table.Cell>
300+
<Table.Cell>
301+
`238.00`
302+
</Table.Cell>
303+
<Table.Cell>
304+
`160.00`
305+
</Table.Cell>
306+
<Table.Cell>
307+
`~33%`
308+
</Table.Cell>
309+
</Table.Row>
310+
<Table.Row>
311+
<Table.Cell>
312+
`POST /store/payment-collections/:id/payments`
313+
</Table.Cell>
314+
<Table.Cell>
315+
`152.00`
316+
</Table.Cell>
317+
<Table.Cell>
318+
`102.00`
319+
</Table.Cell>
320+
<Table.Cell>
321+
`~33%`
322+
</Table.Cell>
323+
</Table.Row>
324+
</Table.Body>
325+
</Table>
326+
327+
---
328+
329+
## Opt-Out of Medusa Cache
330+
331+
If you want to disable Medusa Cache for your Medusa project, you can do so by disabling the `caching` feature flag in `medusa-config.ts`:
332+
333+
```ts title="medusa-config.ts"
334+
module.exports = defineConfig({
335+
// ...
336+
featureFlags: {
337+
caching: false
338+
}
339+
})
340+
```
341+
342+
This will disable all Medusa Cache functionality in your project.

‎www/apps/cloud/app/page.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Refer to the [Sign Up for Cloud](./sign-up/page.mdx) guide to get started.
2323
- **Multiple Environments**: Create multiple long-lived environments for your projects, such as production and staging, to test changes before going live.
2424
- **Instant Preview Environments**: Isolated preview environments are created on every pull request in your repository.
2525
- **Managed Resources**: Medusa manages your project's resources, including a Postgres database, a Redis server, and an S3 bucket.
26+
- **Medusa Cache**: Benefit from performance improvements of business-critical APIs by reducing heavy operations to the database. [Medusa Cache](./cache/page.mdx) is available out of the box at no additional cost.
2627
- **Zero Downtime Deployments**: Medusa rolls out changes to production with zero downtime, never interrupting your users.
2728
- **Autoscaling**: Environments scale to meet traffic demands.
2829
- **Logging**: Monitor your project's runtime and build logs, so you can easily debug issues in your project.

‎www/apps/cloud/generated/edit-dates.mjs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
export const generatedEditDates = {
2-
"app/page.mdx": "2025-09-11T15:21:38.987Z",
2+
"app/page.mdx": "2025-10-13T10:56:37.352Z",
33
"app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
44
"app/projects/page.mdx": "2025-10-17T13:38:32.827Z",
55
"app/environments/page.mdx": "2025-10-15T15:25:09.940Z",
@@ -24,5 +24,6 @@ export const generatedEditDates = {
2424
"app/sign-up/page.mdx": "2025-10-08T14:40:47.993Z",
2525
"app/comparison/page.mdx": "2025-09-30T06:17:40.257Z",
2626
"app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z",
27+
"app/cache/page.mdx": "2025-10-15T06:31:14.375Z",
2728
"app/deployments/troubleshooting/page.mdx": "2025-10-17T14:44:22.894Z"
2829
}

‎www/apps/cloud/generated/sidebar.mjs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,14 @@ export const generatedSidebars = [
149149
"title": "S3",
150150
"path": "/s3",
151151
"children": []
152+
},
153+
{
154+
"loaded": true,
155+
"isPathHref": true,
156+
"type": "link",
157+
"title": "Cache",
158+
"path": "/cache",
159+
"children": []
152160
}
153161
]
154162
},

‎www/apps/cloud/sidebar.mjs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,11 @@ export const sidebar = [
102102
title: "S3",
103103
path: "/s3",
104104
},
105+
{
106+
type: "link",
107+
title: "Cache",
108+
path: "/cache",
109+
},
105110
],
106111
},
107112
{

0 commit comments

Comments
 (0)