docs: cache in cloud (#13719)

* docs: cache in cloud

* fix build

* information updates

* add opt out info

* fix vale error

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

@@ -0,0 +1,342 @@
+import { Prerequisites, Table } from "docs-ui"
+
+export const metadata = {
+  title: `Medusa Cache`,
+}
+
+# {metadata.title}
+
+In this guide, you'll learn about Medusa Cache.
+
+## What is Medusa Cache?
+
+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.
+
+Medusa Cache relies on the existing key/value [Redis](../redis/page.mdx) store already provisioned for environments. Each environment has its own isolated cache.
+
+![Diagram showcasing Redis isolation between environments](https://res.cloudinary.com/dza7lstvk/image/upload/v1750230910/Cloud/redis-cloud_llg83c.jpg)
+
+---
+
+## How Does Medusa Cache Work?
+
+### Enabled by Default
+
+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.
+
+### Cached Data in API Routes
+
+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:
+
+- Regions
+- Promotion codes
+- Variant price sets
+- Variants
+- Shipping options
+- Sales channels
+- Customers
+
+### Integrated into Query
+
+{/* 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. */}
+
+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.
+
+You can enable caching for your custom `query.graph` calls by passing a `cache` option. For example:
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "handle"],
+}, {
+  cache: {
+    enable: true
+  }
+})
+```
+
+This code caches the query result. When the same query is made again, the cached result is returned instead of querying the database.
+
+![Diagram showcasing cache miss and cache hit](https://res.cloudinary.com/dza7lstvk/image/upload/v1759999050/Cloud/medusa-cache-overview_zqpwuo.jpg)
+
+### Automatic Invalidation
+
+By default, data is cached for one hour or until invalidated. Invalidation occurs automatically when related data is created, updated, or deleted.
+
+{/* Learn more about automatic invalidation in the [Caching Module documentation](!resources!/infrastructure-modules/caching/concepts#automatic-cache-invalidation). */}
+
+Learn more about automatic invalidation in the [Caching Module documentation](#).
+
+---
+
+## Performance Benchmark Comparisons
+
+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.
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell className="w-1/2">
+        Endpoint
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Without Medusa Cache (ms)
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        With Medusa Cache (ms)
+      </Table.HeaderCell>
+      <Table.HeaderCell>
+        Improvement
+      </Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
+        **Product Operations**
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/products`
+      </Table.Cell>
+      <Table.Cell>
+        `354.00`
+      </Table.Cell>
+      <Table.Cell>
+        `83.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~77%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/product-categories`
+      </Table.Cell>
+      <Table.Cell>
+        `88.00`
+      </Table.Cell>
+      <Table.Cell>
+        `51.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~42%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/products/:id`
+      </Table.Cell>
+      <Table.Cell>
+        `161.00`
+      </Table.Cell>
+      <Table.Cell>
+        `123.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~24%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
+        **Cart Operations**
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/carts/:id/line-items`
+      </Table.Cell>
+      <Table.Cell>
+        `697.00`
+      </Table.Cell>
+      <Table.Cell>
+        `427.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~39%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/carts/:id/shipping-methods`
+      </Table.Cell>
+      <Table.Cell>
+        `1002.00`
+      </Table.Cell>
+      <Table.Cell>
+        `670.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~33%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/carts/:id/promotions`
+      </Table.Cell>
+      <Table.Cell>
+        `302.00`
+      </Table.Cell>
+      <Table.Cell>
+        `203.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~33%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/carts/:id`
+      </Table.Cell>
+      <Table.Cell>
+        `109.00`
+      </Table.Cell>
+      <Table.Cell>
+        `73.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~33%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/carts/:id`
+      </Table.Cell>
+      <Table.Cell>
+        `909.00`
+      </Table.Cell>
+      <Table.Cell>
+        `656.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~28%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/carts`
+      </Table.Cell>
+      <Table.Cell>
+        `446.00`
+      </Table.Cell>
+      <Table.Cell>
+        `329.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~26%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/carts/:id/complete`
+      </Table.Cell>
+      <Table.Cell>
+        `1357.00`
+      </Table.Cell>
+      <Table.Cell>
+        `1018.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~25%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
+        **Order Operations**
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/orders/:id`
+      </Table.Cell>
+      <Table.Cell>
+        `119.00`
+      </Table.Cell>
+      <Table.Cell>
+        `81.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~32%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
+        **Other Operations**
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/regions`
+      </Table.Cell>
+      <Table.Cell>
+        `89.00`
+      </Table.Cell>
+      <Table.Cell>
+        `51.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~43%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `GET /store/shipping-options`
+      </Table.Cell>
+      <Table.Cell>
+        `272.00`
+      </Table.Cell>
+      <Table.Cell>
+        `173.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~36%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/payment-collections`
+      </Table.Cell>
+      <Table.Cell>
+        `238.00`
+      </Table.Cell>
+      <Table.Cell>
+        `160.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~33%`
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+        `POST /store/payment-collections/:id/payments`
+      </Table.Cell>
+      <Table.Cell>
+        `152.00`
+      </Table.Cell>
+      <Table.Cell>
+        `102.00`
+      </Table.Cell>
+      <Table.Cell>
+        `~33%`
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+
+---
+
+## Opt-Out of Medusa Cache
+
+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`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  // ...
+  featureFlags: {
+    caching: false
+  }
+})
+```
+
+This will disable all Medusa Cache functionality in your project.

www/apps/cloud/app/page.mdx

@@ -23,6 +23,7 @@ Refer to the [Sign Up for Cloud](./sign-up/page.mdx) guide to get started.
 - **Multiple Environments**: Create multiple long-lived environments for your projects, such as production and staging, to test changes before going live.
 - **Instant Preview Environments**: Isolated preview environments are created on every pull request in your repository.
 - **Managed Resources**: Medusa manages your project's resources, including a Postgres database, a Redis server, and an S3 bucket.
+- **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.
 - **Zero Downtime Deployments**: Medusa rolls out changes to production with zero downtime, never interrupting your users.
 - **Autoscaling**: Environments scale to meet traffic demands.
 - **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

@@ -1,5 +1,5 @@
 export const generatedEditDates = {
-  "app/page.mdx": "2025-09-11T15:21:38.987Z",
+  "app/page.mdx": "2025-10-13T10:56:37.352Z",
   "app/organization/page.mdx": "2025-06-12T14:43:20.772Z",
   "app/projects/page.mdx": "2025-10-17T13:38:32.827Z",
   "app/environments/page.mdx": "2025-10-15T15:25:09.940Z",
@@ -24,5 +24,6 @@ export const generatedEditDates = {
   "app/sign-up/page.mdx": "2025-10-08T14:40:47.993Z",
   "app/comparison/page.mdx": "2025-09-30T06:17:40.257Z",
   "app/billing/plans/page.mdx": "2025-10-08T14:49:27.009Z",
+  "app/cache/page.mdx": "2025-10-15T06:31:14.375Z",
   "app/deployments/troubleshooting/page.mdx": "2025-10-17T14:44:22.894Z"
 }

www/apps/cloud/generated/sidebar.mjs

@@ -149,6 +149,14 @@ export const generatedSidebars = [
             "title": "S3",
             "path": "/s3",
             "children": []
+          },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "title": "Cache",
+            "path": "/cache",
+            "children": []
           }
         ]
       },

www/apps/cloud/sidebar.mjs

@@ -102,6 +102,11 @@ export const sidebar = [
             title: "S3",
             path: "/s3",
           },
+          {
+            type: "link",
+            title: "Cache",
+            path: "/cache",
+          },
         ],
       },
       {