asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: Caching Module (#13701)

Browse Source 
* standard docs for caching module + deprecated cache module

* added guides for creating + using, and overall changes from cache to caching

* fix details related to redis provider

* fix build errors

* fix build error

* fixes

* add guides to sidebar

* add sidebar util

* document query + index

* moved cache tag conventions

* fix build errors

* added migration guide

* added memcached guide

* fixes

* general fixes and updates

* updated reference

* document medusa cache

* small fix

* fixes

* remove cloud cache

* revert edit dates changes

* revert edit dates

* small update
This commit is contained in:
Shahed Nasser
2025-10-21 10:34:27 +03:00
committed by GitHub
parent eefda0edce
commit 76f9da5ef4
50 changed files with 10530 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
www/apps/book/app/learn/configurations/medusa-config/page.mdx
View File

@@ -701,7 +701,7 @@ The value of this configuration is prepended to `sess:`. For example, if you set
<Note>
This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](!resources!/infrastructure-modules/cache/redis).
This configuration is not used for modules that also connect to Redis, such as the [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis).
</Note>
@@ -719,9 +719,9 @@ module.exports = defineConfig({
### redisUrl
The `projectConfig.redisUrl` configuration specifies the connection URL to Redis to store the Medusa server session. When specified, the Medusa server uses Redis to store the session data. Otherwie, the session data is stored in-memory.
The `projectConfig.redisUrl` configuration specifies the connection URL to Redis to store the Medusa server session. When specified, the Medusa server uses Redis to store the session data. Otherwise, the session data is stored in-memory.
This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](!resources!/infrastructure-modules/cache/redis). You'll have to configure the Redis connection for those modules separately.
This configuration is not used for modules that also connect to Redis, such as the [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis). You'll have to configure the Redis connection for those modules separately.
<Note>
@@ -764,7 +764,7 @@ The `projectConfig.sessionOptions` configuration defines additional options to p
<Note>
This configuration is not used for modules that also connect to Redis, such as the [Redis Cache Module](!resources!/infrastructure-modules/cache/redis).
This configuration is not used for modules that also connect to Redis, such as the [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis).
</Note>

23
www/apps/book/app/learn/deployment/general/page.mdx
View File

@@ -120,11 +120,11 @@ So, add the following script in `package.json`:
## 3. Install Production Modules and Providers
By default, your Medusa application uses modules and providers useful for development, such as the In-Memory Cache Module or the Local File Module Provider.
By default, your Medusa application uses modules and providers useful for development, such as the Local File Module Provider.
It’s highly recommended to instead use modules and providers suitable for production, including:
- [Redis Cache Module](!resources!/infrastructure-modules/cache/redis)
- [Redis Caching Module](!resources!/infrastructure-modules/caching/providers/redis)
- [Redis Event Bus Module](!resources!/infrastructure-modules/event/redis)
- [Workflow Engine Redis Module](!resources!/infrastructure-modules/workflow-engine/redis)
- [Redis Locking Module Provider](!resources!/infrastructure-modules/locking/redis)
@@ -132,6 +132,12 @@ It’s highly recommended to instead use modules and providers suitable for prod
- [S3 File Module Provider](!resources!/infrastructure-modules/file/s3) (or other file module providers that are production-ready).
- [SendGrid Notification Module Provider](!resources!/infrastructure-modules/notification/sendgrid) (or other notification module providers that are production-ready).
<Note>
The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module.
</Note>
Then, add these modules in `medusa-config.ts`:
```ts title="medusa-config.ts"
@@ -141,9 +147,18 @@ module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/cache-redis",
resolve: "@medusajs/medusa/caching",
options: {
redisUrl: process.env.REDIS_URL,
providers: [
{
resolve: "@medusajs/cache-redis",
id: "caching-redis",
is_default: true,
options: {
redisUrl: process.env.CACHE_REDIS_URL,
},
},
],
},
},
{

334
www/apps/book/app/learn/fundamentals/module-links/index-module/page.mdx
View File

@@ -1,3 +1,5 @@
import { Prerequisites, TypeList } from "docs-ui"
export const metadata = {
title: `${pageNumber} Index Module`,
}
@@ -341,6 +343,338 @@ For example, this is the response returned by the above API route:
---
## Cache Index Module Results
<Prerequisites
items={[
{
text: "Caching Module installed with a provider.",
link: "!resources!/infrastructure-modules/caching#install-the-caching-module"
}
]}
/>
<Note>
Caching options are available from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
</Note>
You can cache Index Module results to improve performance and reduce database load. To do that, you can pass a `cache` property in the second parameter of the `query.index` method.
For example, to enable caching for a query:
```ts highlights={[["6", "enable", "Enable caching for this query."]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true
}
})
```
In this example, you enable caching of the query's results. The next time the same query is executed, the results are returned from the cache instead of querying the database.
<Note title="Tip">
Refer to the [Caching Module documentation](!resources!/infrastructure-modules/caching/concepts#caching-best-practices) for best practices on caching.
</Note>
### Cache Properties
`cache` is an object that accepts the following properties:
<TypeList
types={[
{
type: "`boolean` \| `((args: any[]) => boolean \| undefined)`",
name: "enable",
description: "Whether to enable caching of query results. If a function is passed, it receives as a parameter the `query.index` parameters, and returns a boolean indicating whether caching is enabled.",
defaultValue: "false"
},
{
type: "`string` \| `((args: any[], cachingModule: ICachingModuleService) => string \| Promise<string>)`",
name: "key",
description: "The key to cache the query results with. If no key is provided, the Caching Module will generate the key from the `query.index` parameters.\n\nIf a function is passed, it receives the following properties:\n\n1. The parameters passed to `query.index`.\n\n2. The [Caching Module's service](!resources!/references/caching-service), which you can use to perform caching operations.\n\nThe function must return a string indicating the cache key.",
},
{
type: "`string[]` \| `((args: any[]) => string[] \| undefined)`",
name: "tags",
description: "The tags to associate with the cached results. Tags are useful to group related items. If no tag is provided, the Caching Module will generate relevant tags based on the entity and its retrieved relations.\n\nIf a function is passed, it receives as a parameter the `query.index` parameters, and returns an array of strings indicating the cache tags."
},
{
type: "`number` \| `((args: any[]) => number \| undefined)`",
name: "ttl",
description: "The time-to-live (TTL) for the cached results, in seconds. If no TTL is provided, the Caching Module Provider will receive the [configured TTL of the Caching Module](!resources!/infrastructure-modules/caching#caching-module-options), or it will use its own default value.\n\nIf a function is passed, it receives as a parameter the `query.index` parameters, and returns a number indicating the TTL.",
},
{
type: "`boolean` \| `((args: any[]) => boolean \| undefined)`",
name: "autoInvalidate",
description: "Whether to automatically invalidate the cached data when it expires.\n\nIf a function is passed, it receives as a parameter the `query.index` parameters, and returns a boolean indicating whether to automatically invalidate the cache.",
defaultValue: "`true`"
},
{
type: "`string[]` \| `((args: any[]) => string[] \| undefined)`",
name: "providers",
description: "The IDs of the providers to use for caching. If not provided, the [default Caching Module Provider](!resources!/infrastructure-modules/caching/providers#default-caching-module-provider) is used. If multiple providers are passed, the cache is stored and retrieved in those providers in order.\n\nIf a function is passed, it receives as a parameter the `query.index` parameters, and return an array of strings indicating the providers to use."
}
]}
sectionTitle="Cache Properties"
/>
### Set Cache Key
By default, the Caching Module generates a cache key for a query based on the arguments passed to `query.index`. The cache key is a unique key that the cached result is stored with.
Alternatively, you can set a custom cache key for a query. This is useful if you want to manage invalidating the cache manually.
To set the cache key of a query, pass the `cache.key` option:
```ts highlights={[["7"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
key: "products-123456",
// to disable auto invalidation:
// autoInvalidate: false,
}
})
```
In the example above, you cache the query results with the `products-123456` key.
<Note>
You should generate cache keys with the Caching Module service's [computeKey method](!resources!/references/caching-service#computeKey) to ensure that the key is unique and follows best practices.
</Note>
You can also pass a function as the value of `cache.key`:
```ts highlights={[["7"], ["8"], ["9"], ["10"], ["11"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
key: async (args, cachingModuleService) => {
return await cachingModuleService.computeKey({
...args,
prefix: "products"
})
}
}
})
```
In the example above, you pass a function to `key`. It accepts two parameters:
1. The arguments of `query.index` passed as an array.
2. The [Caching Module's service](!resources!/references/caching-service).
You generate the key using the [computeKey method of the Caching Module's service](!resources!/references/caching-service#computeKey). The query results will be cached with that key.
### Set Cache Tags
By default, the Caching Module generates relevant tags for a query based on the entity and its retrieved relations. Cache tags are useful to group related items together, allowing you to [retrieve](!resources!/references/caching-service#get) or [invalidate](!resources!/references/caching-service#clear) items by common tags.
Alternatively, you can set the cache tags of a query manually. This is useful if you want to manage invalidating the cache manually, or you want to group related cached items with custom tags.
To set the cache tags of a query, pass the `cache.tags` option:
```ts highlights={[["7"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
tags: ["Product:list:*"],
}
})
```
In the example above, you cache the query results with the `Product:list:*` tag.
<Note>
The cache tag must follow the [Caching Tags Convention](!resources!/infrastructure-modules/caching/concepts#caching-tags-convention) to be automatically invalidated.
</Note>
You can also pass a function as the value of `cache.tags`:
```ts highlights={[["7"], ["8"], ["9"], ["10"], ["11"], ["12"], ["13"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
tags: (args) => {
const collectionId = args[0].filter?.collection_id
return [
...args,
collectionId ? `ProductCollection:${collectionId}` : undefined,
]
},
}
})
```
In the example above, you use a function to determine the cache tags. The function accepts the arguments passed to `query.index` as an array.
Then, you add the `ProductCollection:id` tag if `collection_id` is passed in the query filters.
### Set TTL
By default, the Caching Module will pass the [configured time-to-live (TTL)](!resources!/infrastructure-modules/caching#caching-module-options) to the Caching Module Provider when caching data. The Caching Module Provider may also have its own default TTL. The cache isn't invalidated until the configured TTL passes.
Alternatively, you can set a custom TTL for a query. This is useful if you want the cached data to be invalidated sooner or later than the default TTL.
To set the TTL of the cached query results to a custom value, use the `cache.ttl` option:
```ts highlights={[["7"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
ttl: 100, // 100 seconds
}
})
```
In the example above, you set the TTL of the cached query result to `100` seconds. It will be invalidated after that time.
You can also pass a function as the value of `cache.ttl`:
```ts highlights={[["10"], ["11"], ["12"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
filters: {
id: "prod_123"
}
}, {
cache: {
enable: true,
ttl: (args) => {
return args[0].filters.id === "test" ? 10 : 100
}
}
})
```
In the example above, you use a function to determine the TTL. The function accepts the arguments passed to `query.index` as an array.
Then, you set the TTL based on the ID of the product passed in the filters.
### Set Auto Invalidation
By default, the Caching Module automatically invalidates cached query results when the data changes.
Alternatively, you can disable auto invalidation of cached query results. This is useful if you want to manage invalidating the cache manually.
To configure invalidation behavior, use the `cache.autoInvalidate` option:
```ts highlights={[["7"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
autoInvalidate: false,
}
})
```
In this example, you disable auto invalidation of the query result. You must [invalidate](!resources!/references/caching-service#clear) the cached data manually.
You can also pass a function as the value of `cache.autoInvalidate`:
```ts highlights={[["7"], ["8"], ["9"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
autoInvalidate: (args) => {
return !args[0].fields.includes("custom_field")
}
}
})
```
In the example above, you use a function to determine whether to invalidate the cached query result automatically. The function accepts the arguments passed to `query.index` as an array.
Then, you enable auto-invalidation only if the `fields` passed to `query.index` don't include `custom_fields`. If this disables auto-invalidation, you must [invalidate](!resources!/references/caching-service#clear) the cached data manually.
<Note title="Tip">
Learn more about automatic invalidation in the [Caching Module documentation](!resources!/infrastructure-modules/caching/concepts#automatic-cache-invalidation).
</Note>
### Set Caching Provider
By default, the Caching Module uses the [default Caching Module Provider](!resources!/infrastructure-modules/caching/providers#default-caching-module-provider) to cache a query.
Alternatively, you can set the caching provider to use for a query. This is useful if you have multiple caching providers configured, and you want to use a specific one for a query, or you want to specify a fallback provider.
To configure the caching providers, use the `cache.providers` option:
```ts highlights={[["7"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
providers: ["caching-redis", "caching-memcached"]
}
})
```
In the example above, you specify the providers with ID `caching-redis` and `caching-memcached` to cache the query results. These IDs must match the IDs of the providers in `medusa-config.ts`.
When you pass multiple providers, the cache is stored and retrieved in those providers in order.
You can also pass a function as the value of `cache.providers`:
```ts highlights={[["10"], ["11"], ["12"]]}
const { data: products } = await query.index({
entity: "product",
fields: ["id", "title"],
filters: {
id: "prod_123"
}
}, {
cache: {
enable: true,
providers: (args) => {
return args[0].filters.id === "test" ? ["caching-redis"] : ["caching-memcached"]
}
}
})
```
In the example above, you use a function to determine the caching providers. The function accepts the arguments passed to `query.index` as an array.
Then, you set the providers based on the ID of the product passed in the filters.
---
## index Method Usage Examples
The following sections show examples of how to use the `index` method in different scenarios.

908
www/apps/book/app/learn/fundamentals/module-links/query/page.mdx
View File

File diff suppressed because it is too large Load Diff

22
www/apps/book/app/learn/fundamentals/modules/infrastructure-modules/page.mdx
View File

@@ -18,15 +18,21 @@ Since modules are interchangeable, you have more control over Medusa’s archite
There are different Infrastructure Module types including:
![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1727095814/Medusa%20Book/architectural-modules_bj9bb9.jpg)
![Diagram illustrating how the modules connect to third-party services](https://res.cloudinary.com/dza7lstvk/image/upload/v1759762284/Medusa%20Book/service-infra_k3fcy0.jpg)
- Analytics Module: Integrates a third-party service to track and analyze user interactions and system events.
- Cache Module: Defines the caching mechanism or logic to cache computational results.
- Event Module: Integrates a pub/sub service to handle subscribing to and emitting events.
- Workflow Engine Module: Integrates a service to store and track workflow executions and steps.
- File Module: Integrates a storage service to handle uploading and managing files.
- Notification Module: Integrates a third-party service or defines custom logic to send notifications to users and customers.
- Locking Module: Integrates a service that manages access to shared resources by multiple processes or threads.
- [Analytics Module](!resources!/infrastructure-modules/analytics): Integrates a third-party service to track and analyze user interactions and system events.
- [Caching Module](!resources!/infrastructure-modules/caching): Defines the caching mechanism or logic to cache computational results.
- [Event Module](!resources!/infrastructure-modules/event): Integrates a pub/sub service to handle subscribing to and emitting events.
- [Workflow Engine Module](!resources!/infrastructure-modules/workflow-engine): Integrates a service to store and track workflow executions and steps.
- [File Module](!resources!/infrastructure-modules/file): Integrates a storage service to handle uploading and managing files.
- [Notification Module](!resources!/infrastructure-modules/notification): Integrates a third-party service or defines custom logic to send notifications to users and customers.
- [Locking Module](!resources!/infrastructure-modules/locking): Integrates a service that manages access to shared resources by multiple processes or threads.
<Note>
The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module.
</Note>
---

16
www/apps/book/app/learn/introduction/architecture/page.mdx
View File

@@ -29,7 +29,7 @@ These layers of stack can be implemented within [plugins](../../fundamentals/plu
</Note>
![Medusa application architecture diagram illustrating the HTTP layer flow: External clients (storefront and admin) send requests to API routes, which execute workflows containing business logic, which then interact with modules to perform data operations on PostgreSQL databases](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175296/Medusa%20Book/http-layer_sroafr.jpg)
![Medusa application architecture diagram illustrating the HTTP layer flow: External clients (storefront and admin) send requests to API routes, which execute workflows containing business logic, which then interact with modules to perform data operations on PostgreSQL databases](https://res.cloudinary.com/dza7lstvk/image/upload/v1759761784/Medusa%20Book/http-layer-new_hu0r3h.jpg)
---
@@ -43,7 +43,7 @@ Modules can be implemented within [plugins](../../fundamentals/plugins/page.mdx)
</Note>
![Database layer architecture diagram showing how Medusa modules establish connections to PostgreSQL databases through injected database connections, enabling data persistence and retrieval operations](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175379/Medusa%20Book/db-layer_pi7tix.jpg)
![Database layer architecture diagram showing how Medusa modules establish connections to PostgreSQL databases through injected database connections, enabling data persistence and retrieval operations](https://res.cloudinary.com/dza7lstvk/image/upload/v1759761866/Medusa%20Book/db-layer-new_faeksx.jpg)
---
@@ -72,7 +72,7 @@ You can replace any of the third-party services mentioned above to build your pr
[Infrastructure Modules](!resources!/infrastructure-modules) integrate third-party services and systems that customize Medusa's infrastructure. Medusa has the following Infrastructure Modules:
- [Analytics Module](!resources!/infrastructure-modules/analytics): Tracks and analyzes user interactions and system events with third-party analytic providers. You can integrate [PostHog](!resources!/infrastructure-modules/analytics/posthog) as the analytics provider.
- [Cache Module](!resources!/infrastructure-modules/cache): Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing [Redis Cache Module](!resources!/infrastructure-modules/cache/redis).
- [Caching Module](!resources!/infrastructure-modules/caching): Caches data that require heavy computation. You can integrate a custom module to handle the caching with services like Memcached, or use the existing [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis).
- [Event Module](!resources!/infrastructure-modules/event): A pub/sub system that allows you to subscribe to events and trigger them. You can integrate [Redis](!resources!/infrastructure-modules/event/redis) as the pub/sub system.
- [File Module](!resources!/infrastructure-modules/file): Manages file uploads and storage, such as upload of product images. You can integrate [AWS S3](!resources!/infrastructure-modules/file/s3) for file storage.
- [Locking Module](!resources!/infrastructure-modules/locking): Manages access to shared resources by multiple processes or threads, preventing conflict between processes and ensuring data consistency. You can integrate [Redis](!resources!/infrastructure-modules/locking/redis) for locking.
@@ -81,7 +81,13 @@ You can replace any of the third-party services mentioned above to build your pr
All of the third-party services mentioned above can be replaced to help you build your preferred architecture and ecosystem.
![Diagram illustrating the Infrastructure Modules integration to third-party services and systems](https://res.cloudinary.com/dza7lstvk/image/upload/v1727175342/Medusa%20Book/service-arch_ozvryw.jpg)
<Note>
The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module.
</Note>
![Diagram illustrating the Infrastructure Modules integration to third-party services and systems](https://res.cloudinary.com/dza7lstvk/image/upload/v1759762284/Medusa%20Book/service-infra_k3fcy0.jpg)
---
@@ -89,4 +95,4 @@ All of the third-party services mentioned above can be replaced to help you buil
The following diagram illustrates Medusa's architecture including all its layers.
![Complete Medusa architecture overview showing the full technology stack: client applications (storefront and admin) connecting through HTTP layer to workflows, which coordinate with commerce and Infrastructure Modules to manage data operations, third-party integrations, and database persistence](https://res.cloudinary.com/dza7lstvk/image/upload/v1727174897/Medusa%20Book/architectural-diagram-full.jpg)
![Complete Medusa architecture overview showing the full technology stack: client applications (storefront and admin) connecting through HTTP layer to workflows, which coordinate with commerce and Infrastructure Modules to manage data operations, third-party integrations, and database persistence](https://res.cloudinary.com/dza7lstvk/image/upload/v1759762329/Medusa%20Book/diagram-full-new_znssjy.jpg)

4
www/apps/book/app/learn/introduction/from-v1-to-v2/page.mdx
View File

@@ -125,7 +125,7 @@ npm install
<Note title="Medusa Module Dependencies" forceMultiline>
In Medusa v1, you needed to install Medusa modules like the Cache, Event, or Pricing modules.
In Medusa v1, you needed to install Medusa modules like the Event, Product, or Pricing modules.
These modules are now available out of the box, and you don't need to install or configure them separately.
@@ -375,7 +375,7 @@ While the `plugins` configuration hasn't changed, plugins available in Medusa v1
In Medusa v1, you had to configure modules like Inventory, Stock Location, Pricing, and Product. These modules are now available out of the box, and you don't need to install or configure them separately.
For the Cache and Event modules, refer to the [Redis Cache Module](!resources!/infrastructure-modules/cache/redis) and [Redis Event Module](!resources!/infrastructure-modules/event/redis) documentations to learn how to configure them in v2 if you had them configured in v1.
For the Cache and Event modules, refer to the [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis) and [Redis Event Module](!resources!/infrastructure-modules/event/redis) documentations to learn how to configure them in v2 if you had them configured in v1.
#### Feature Flags

2937
www/apps/book/public/llms-full.txt
View File

File diff suppressed because it is too large Load Diff

8
www/apps/cloud/app/projects/page.mdx
View File

@@ -70,7 +70,7 @@ Your existing Medusa application doesn't need specific configurations to be depl
- Create the necessary [server and worker instances](!docs!/learn/production/worker-mode).
- Scale your Medusa application's resources based on the traffic it receives.
- Set up and configure production resources and modules for your Medusa application:
- [Redis Cache Module](!resources!/infrastructure-modules/cache/redis)
- [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis)
- [Redis Event Module](!resources!/infrastructure-modules/event/redis)
- [Redis Locking Module Provider](!resources!/infrastructure-modules/locking/redis)
- [Redis Workflow Engine Module](!resources!/infrastructure-modules/workflow-engine/redis)
@@ -78,6 +78,12 @@ Your existing Medusa application doesn't need specific configurations to be depl
So, make sure to remove any of these modules from your `medusa-config.ts` file, unless you want to use custom options for them. In that case, you're expected to manually set up and manage those resources externally and configure them in your Medusa application.
<Note>
The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module. If you're still using the Cache Module, make sure to remove it from your `medusa-config.ts` file as well.
</Note>
### Project Creation Steps
To create a project from an existing Medusa application:

8
www/apps/cloud/app/redis/page.mdx
View File

@@ -21,7 +21,7 @@ Each project environment has a dedicated Redis server. These Redis servers are e
Medusa automatically configures your Medusa application hosted on Cloud to use Redis-based Infrastructure Modules, including:
- [Redis Event Module](!resources!/infrastructure-modules/event/redis)
- [Redis Cache Module](!resources!/infrastructure-modules/cache/redis)
- [Redis Caching Module Provider](!resources!/infrastructure-modules/caching/providers/redis)
- [Redis Locking Module Provider](!resources!/infrastructure-modules/locking/redis)
- [Redis Workflow Engine Module](!resources!/infrastructure-modules/workflow-engine/redis)
@@ -33,6 +33,12 @@ If you're using a Medusa version before v2.7.0, contact support for assistance i
</Note>
<Note title="Tip">
The Caching Module was introduced in [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0) to replace the deprecated Cache Module.
</Note>
### Access Redis Configurations on Cloud
Since Cloud is a managed service, you can't directly access your Redis instance or its configurations. Medusa also doesn't expose the Redis instance connection or configuration details.

8
www/apps/resources/app/infrastructure-modules/cache/create/page.mdx vendored
View File

@@ -14,6 +14,14 @@ export const metadata = {
In this guide, you’ll learn how to create a Cache Module.
{/* TODO add link */}
<Note title="Deprecation Notice">
The Cache Module is deprecated starting from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). [Create a Caching Module Provider](#) instead.
</Note>
## 1. Create Module Directory
Start by creating a new directory for your module. For example, `src/modules/my-cache`.

6
www/apps/resources/app/infrastructure-modules/cache/in-memory/page.mdx vendored
View File

@@ -12,6 +12,12 @@ This module is helpful for development or when you’re testing out Medusa, but
For production, it’s recommended to use modules like [Redis Cache Module](../redis/page.mdx).
<Note title="Deprecation Notice">
The In-Memory Cache Module is deprecated starting from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). Use the [Caching Module](../../caching/page.mdx) instead.
</Note>
---
## Register the In-Memory Cache Module

6
www/apps/resources/app/infrastructure-modules/cache/page.mdx vendored
View File

@@ -8,6 +8,12 @@ export const metadata = {
In this document, you'll learn what a Cache Module is and how to use it in your Medusa application.
<Note title="Deprecation Notice">
The Cache Module is deprecated starting from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). Use the [Caching Module](../caching/page.mdx) instead.
</Note>
## What is a Cache Module?
A Cache Module is used to cache the results of computations such as price selection or various tax calculations.

8
www/apps/resources/app/infrastructure-modules/cache/redis/page.mdx vendored
View File

@@ -8,9 +8,9 @@ export const metadata = {
The Redis Cache Module uses Redis to cache data in your store. In production, it's recommended to use this module.
<Note title="Using Cloud?">
<Note title="Deprecation Notice">
Our Cloud offering automatically provisions a Redis instance and configures the Redis Cache Module for you. Learn more in the [Redis](!cloud!/redis) Cloud documentation.
The Redis Cache Module is deprecated starting from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). Use the [Redis Caching Module Provider](../../caching/providers/redis/page.mdx) instead.
</Note>
@@ -32,10 +32,6 @@ export const highlights = [
]
```ts title="medusa-config.ts" highlights={highlights}
import { Modules } from "@medusajs/framework/utils"
// ...
module.exports = defineConfig({
// ...
modules: [

247
www/apps/resources/app/infrastructure-modules/caching/concepts/page.mdx Normal file
View File

@@ -0,0 +1,247 @@
export const metadata = {
title: `Caching Module Concepts`,
}
# {metadata.title}
In this guide, you'll learn about the main concepts of the [Caching Module](../page.mdx), including cache keys, cache tags, and automatic cache invalidation.
## Cache Keys
Cache keys uniquely identify cached data in the caching service. The Caching Module automatically generates cache keys when you cache data with Query or the Index Module.
### Custom Cache Keys
When you cache custom data with the Caching Module's service, you can generate a cache key using the [computeKey](/references/caching-service#computeKey) method. This method generates a unique key based on the data you want to cache.
For example:
```ts
const data = { id: "prod_123", title: "Product 123" }
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
key,
tags: ["Product:prod_123", "Product:list:*"],
data
})
```
The `computeKey` method takes an object as input and generates a unique key based on its properties.
The generated key is a hash string that uniquely identifies the data. The has doesn't change based on the order of properties in the object.
For example, the following two objects generate the same cache key:
```ts
const key1 = await cachingModuleService.computeKey({ id: "prod_123", title: "Product 123" })
const key2 = await cachingModuleService.computeKey({ title: "Product 123", id: "prod_123" })
console.log(key1 === key2) // true
```
### When to Use Custom Cache Keys?
Use custom cache keys when you're caching custom data with the Caching Module's service. This ensures that the cached data is uniquely identified and can be retrieved or invalidated correctly.
You can also pass a custom key to Query or the Index Module when caching data. This is useful when you want to use the key for custom invalidation or retrieval.
Learn more about passing custom keys in the [Query guide](!docs!/learn/fundamentals/module-links/query#set-cache-key).
---
## Cache Tags
Cache tags are useful for grouping cached data, making it easier to invalidate or retrieve related cached entries.
When you cache data with the Query or Index Module, the Caching Module automatically generates cache tags based on the entity being queried and its retrieved relations.
When you cache custom data with the Caching Module's service, you can pass custom tags to the `set` and `get` methods.
### Caching Tags Convention
The Caching Module generates cache tags in the following format:
- `Entity:id`: Cache tag for a single record of an entity. For example, `Product:prod_123` for caching a single product with the ID `prod_123`.
- `Entity:list:*`: Cache tag for a list of records of an entity. For example, `Product:list:*` for caching a list of products.
<Note>
`Entity` is the pascal-cased name of the data model, which you pass as the first parameter to `model.define` when defining the model.
</Note>
When you use custom tags, ensure they adhere to the above convention. Otherwise, the Caching Module cannot automatically invalidate your cached data. You'll have to [invalidate](/references/caching-service#clear) the cached data manually.
For example:
```ts
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
key,
tags: ["Product:list:*", "Product:prod_123"],
data
})
```
### When to Use Custom Tags?
Use custom tags when you want to group cached data for custom invalidation or retrieval.
Note that if your custom tags do not follow the [Caching Tags Convention](#caching-tags-convention), the Caching Module cannot automatically invalidate your cached data. You must manually [invalidate](/references/caching-service#clear) the cached data when it changes.
---
## Automatic Cache Invalidation
### When is Cache Automatically Invalidated?
The Caching Module automatically invalidates cached data when the underlying data changes through database operations such as create, update, or delete.
For example, if you cache a list of products with the tag `Product:list:*` and a new product is created, the Caching Module automatically invalidates the cached list of products.
This ensures that your application always serves fresh data and avoids serving stale or outdated information.
The following table shows when the Caching Module invalidates cached data based on different database operations:
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
Database Operation
</Table.HeaderCell>
<Table.HeaderCell>
Invalidated Cache Tags
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
Create
</Table.Cell>
<Table.Cell>
`Entity:list:*` (`Product:list:*`)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
Update
</Table.Cell>
<Table.Cell>
`Entity:{id}`, `Entity:list:*` if the list includes the updated record. (`Product:prod_123`, `Product:list:*`)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
Delete
</Table.Cell>
<Table.Cell>
`Entity:list:*` (`Product:list:*`)
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
### Which Data is Automatically Invalidated?
The Caching Module automatically invalidates your cached data when:
1. The data includes an `id` field. This is used internally to map the data to the corresponding cache tags.
- When retrieving data with Query or the Index Module, ensure the `id` field is included in the `fields` option.
```ts
const { data: products } = useQueryGraphStep({
entity: "product",
fields: ["id", "title"], // Ensure 'id' is included, or pass '*'
options: {
cache: {
enable: true,
},
},
})
```
- When caching custom data with the Caching Module's service, ensure the data object includes an `id` property.
2. Custom tags follow the [Caching Tags Convention](#caching-tags-convention).
```ts
const data = { id: "prod_123", title: "Product 123" }
const key = await cachingModuleService.computeKey(data)
await cachingModuleService.set({
key,
tags: ["Product:prod_123", "Product:list:*"],
data
})
```
3. The `autoInvalidate` option is not set or is set to `true`. This option is enabled by default.
```ts
const { data: products } = useQueryGraphStep({
entity: "product",
fields: ["id", "title"],
options: {
cache: {
enable: true,
// This is enabled by default
// autoInvalidate: true,
},
},
})
```
### Invalidation of Related Entities
If the cached data includes relations, and the relation is updated, the Caching Module also invalidates the cache tags for the related entity.
For example, consider the following Query usage:
```ts
const { data: products } = useQueryGraphStep({
entity: "product",
fields: ["id", "title", "variants.*"],
options: {
cache: {
enable: true,
},
},
})
```
If the product's variant is updated, the Caching Module invalidates the cache tags for both the `Product` and `ProductVariant` entities.
### When to Disable Automatic Invalidation?
Disabling automatic invalidation means the data remains in the cache until it expires (based on the TTL) or is manually invalidated.
Consider disabling automatic invalidation in the following cases:
1. You're caching data that rarely changes, such as a list of countries.
2. You want to manage cache invalidation manually, such as when caching data as part of a custom workflow where you want to control when the cache is invalidated.
3. You're caching data that does not belong to a Medusa data model, such as data from an external API or computed values. This data is not automatically invalidated by default.
Disable automatic invalidation by setting the `autoInvalidate` option to `false` when caching data with Query, the Index Module, or the Caching Module's service.
When you disable automatic invalidation, manually [invalidate](/references/caching-service#clear) the cached data when it changes.
---
## Caching Best Practices
### Cache Rarely-Changing Data
Cache data that is read frequently but changes infrequently, such as product information, categories, or static content.
Caching such data can significantly improve performance and reduce database load.
### Do Not Cache Dynamic Data
Avoid caching data that changes frequently or is user-specific, such as shopping cart contents, user sessions, or product pricing.
Caching such data can lead to inconsistencies and stale information being served to users. It also increases bandwidth and memory usage, as the cache is updated frequently.
### Do Not Cache Frequently Updated Data
Avoid caching data that is updated frequently, such as inventory levels or order statuses.
Caching such data increases the overhead of cache invalidation and may lead to performance degradation.

1107
www/apps/resources/app/infrastructure-modules/caching/guides/memcached/page.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

124
www/apps/resources/app/infrastructure-modules/caching/migrate-cache/page.mdx Normal file
View File

@@ -0,0 +1,124 @@
import { Prerequisites } from "docs-ui"
export const metadata = {
title: `Migrate from Cache Module to Caching Module`,
}
# {metadata.title}
In this guide, you'll learn how to migrate from the deprecated [Cache Module](../../cache/page.mdx) to the new [Caching Module](../page.mdx).
<Note>
The Caching Module is available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
</Note>
<Note title="This guide is for developers who have">
1. Set up a Cache Module in `medusa-config.ts`.
2. Used the Cache Module's service in their code.
If you haven't done either of these, you don't need to migrate to the Caching Module. You can refer to the [Caching Module guide](../page.mdx#install-the-caching-module) to learn how to set it up.
</Note>
## Why Migrate to the Caching Module?
The Caching Module provides improved performance, flexibility, and scalability compared to the deprecated Cache Module.
It also offers a better developer experience, making it easier to cache Query results and other data.
Additionally, the Caching Module supports registering multiple caching providers, such as Redis and Memcached, allowing you to use different caching backends in your application.
---
## Architectural Module Changes
The Cache Module implements caching logic, including integration with third-party caching services like Redis. For example, the Redis Cache Module handled connecting to the Redis server and performing caching operations.
The Caching Module, on the other hand, follows a provider-based architecture. The Caching Module provides the interface you use to manage cached data, while Caching Module Providers implement the actual caching logic. You can choose which provider to use, such as the Redis Caching Module Provider or a custom provider you create.
This separation of concerns allows for greater flexibility and extensibility. You can easily switch between different caching providers or create your own custom provider without modifying the core Caching Module.
![Diagram illustrating the change in architecture from Cache Module to Caching Module](https://res.cloudinary.com/dza7lstvk/image/upload/v1759845565/Medusa%20Resources/cache-to-caching_yxaped.jpg)
---
## How to Migrate to the Caching Module
<Prerequisites
items={[
{
text: "Updated your Medusa application to v2.11.0 or later",
link: "https://github.com/medusajs/medusa/releases/tag/v2.11.0"
}
]}
/>
### 1. Remove the Cache Module
The first step is to remove the Cache Module from your `medusa-config.ts` file.
For example, if you set up the Redis Cache Module, remove the following code from `medusa-config.ts`:
```ts title="medusa-config.ts" highlights={[["5"], ["6"], ["7"], ["8"], ["9"], ["10"]]}
module.exports = defineConfig({
// ...
modules: [
// REMOVE THE FOLLOWING LINES
{
resolve: "@medusajs/medusa/cache-redis",
options: {
redisUrl: process.env.CACHE_REDIS_URL,
},
},
],
})
```
### 2. Install and Register the Caching Module
The Caching Module is installed by default in your application. To use it, enable the caching feature flag and register the module in your `medusa-config.ts` file.
Refer to the [Caching Module guide](../page.mdx#install-the-caching-module) for setup instructions.
### 3. (Optional) Update Your Code to Use the Caching Module's Service
If you're using the Cache Module's service in your code, update it to use the Caching Module's service instead.
#### Container Key Change
Previously, you resolved the Cache Module's service using the `Modules.CACHE` or `cache` key.
Now, use the `Modules.CACHING` or `caching` key to resolve the Caching Module's service. For example:
```ts
const cachingModuleService = container.resolve(Modules.CACHING)
// or
const cachingModuleService = container.resolve("caching")
```
#### Method Changes
The Caching Module's service has similar methods to the Cache Module's service:
1. `get` -> Use the Caching Module's [get method](/references/caching-service#get).
2. `set` -> Use the Caching Module's [set method](/references/caching-service#set).
3. `invalidate` -> Use the Caching Module's [clear method](/references/caching-service#clear).
### 4. (Optional) Create Custom Caching Module Provider
If you have a custom Cache Module, recreate it as a custom Caching Module Provider. For example, recreate a custom Memcached Cache Module as a Caching Module Provider.
The Caching Module Provider's service has similar methods to the Cache Module's service. Refer to the [Create Caching Module Provider guide](/references/caching-module-provider) for instructions on creating a custom Caching Module Provider.
---
## Understand Caching Changes
With the Cache Module, you handled caching and invalidation manually.
The Caching Module can now handle caching and invalidation automatically for certain operations, such as caching Query results. You can still use the Caching Module's service to cache custom data.
Learn more about the Caching Module in the [Caching Module guide](../page.mdx).

318
www/apps/resources/app/infrastructure-modules/caching/page.mdx Normal file
View File

@@ -0,0 +1,318 @@
import { CardList, Card, Table, CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Caching Module`,
}
# {metadata.title}
In this guide, you'll learn about the Caching Module and its providers.
<Note>
The Caching Module is available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). It replaces the deprecated [Cache Module](../cache/page.mdx).
</Note>
## What is the Caching Module?
The Caching Module provides functionality to cache data in your Medusa application, improving performance and reducing latency for frequently accessed data.
For example, Medusa uses the Caching Module to cache product information, and you can cache custom data such as brand information.
The Caching Module stores and retrieves cached data using the caching service you integrate, such as [Redis](./providers/redis/page.mdx) or [Memcached](./guides/memcached/page.mdx). This provides flexibility in customizing your Medusa application's infrastructure to meet your performance and scalability requirements.
![Diagram illustrating the Caching Module architecture](https://res.cloudinary.com/dza7lstvk/image/upload/v1759846791/Medusa%20Resources/caching-overview_tz91tw.jpg)
### Caching Module vs Cache Module
Before Medusa v2.11.0, you used the [Cache Module](../cache/page.mdx) to cache data. The Cache Module is now deprecated and has been replaced by the Caching Module.
If you're using the Cache Module in your application, refer to the [migrate to the Caching Module](./migrate-cache/page.mdx).
---
## Install the Caching Module
The Caching Module is installed by default in your application. To use it, enable the caching feature flag and register the module in your `medusa-config.ts` file.
{/* <Note title="Cloud user?">
Caching features are enabled by default for Cloud users. Learn more in the [Medusa Cache](!cloud!/cache) guide.
</Note> */}
### 1. Enable Caching Feature Flag
The caching feature is currently behind a feature flag. To enable it, set the `MEDUSA_FF_CACHING` environment variable to `true` in your `.env` file:
```bash
MEDUSA_FF_CACHING=true
```
This enables you to use the Caching Module and activates caching features in Medusa's core.
### 2. Register the Caching Module
Next, add the Caching Module to the `modules` property of the exported object in `medusa-config.ts`:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/caching",
options: {
providers: [
{
resolve: "@medusajs/caching-redis",
id: "caching-redis",
// Optional, makes this the default caching provider
is_default: true,
options: {
redisUrl: process.env.CACHE_REDIS_URL,
// more options...
},
},
]
}
}
]
})
```
This registers the Caching Module in your application with the [Redis Caching Module Provider](./providers/redis/page.mdx).
<Note>
The Caching Module requires at least one Caching Module Provider to be registered. If you do not register any providers, the Caching Module throws an error when your application starts.
</Note>
### What is a Caching Module Provider?
A Caching Module Provider implements the underlying logic for caching data, such as integrating third-party caching services. The Caching Module then uses the registered Caching Module Provider to handle caching operations.
Refer to the [Caching Module Providers guide](./providers/page.mdx) to learn more about Caching Module Providers in Medusa, and how to configure the default provider.
<CardList
items={[
{
title: "Redis",
href: "/infrastructure-modules/caching/providers/redis",
badge: {
variant: "green",
children: "For Production"
}
},
{
title: "Memcached",
href: "/infrastructure-modules/caching/guides/memcached",
badge: {
variant: "blue",
children: "Tutorial"
}
}
]}
/>
### What Data is Cached by Default?
After you enable the Caching Module, Medusa automatically caches data for 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
---
## How to Use the Caching Module
You can cache data with the Caching Module in two ways: by caching data retrieved with [Query](!docs!/learn/fundamentals/module-links/query) or the [Index Module](!docs!/learn/fundamentals/module-links/index-module), or by directly using the [Caching Module's service](/references/caching-service).
### 1. Caching with Query or Index Module
You can cache results from Query and the Index Module by passing the `cache` option to the `query.graph` and `query.index` methods, or to the `useQueryGraphStep` in workflows.
For example:
```ts highlights={[["14"], ["15"], ["16"]]}
import {
createWorkflow,
WorkflowResponse
} from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
export const workflow = createWorkflow(
"workflow-1",
() => {
const { data: products } = useQueryGraphStep({
entity: "product",
fields: ["id", "title"],
options: {
cache: {
enable: true,
},
},
})
return new WorkflowResponse(products)
}
)
```
The `useQueryGraphStep` accepts an `options.cache` property that enables and configures caching of the results.
When caching is enabled, the Caching Module stores the results in the underlying caching service (for example, Redis). Subsequent calls to the same query retrieve the results from the cache, improving performance.
Query and the Index Module accept other caching options. Learn more in the [Query](!docs!/learn/fundamentals/module-links/query#cache-query-results) and [Index Module](!docs!/learn/fundamentals/module-links/index-module#cache-index-module-results) guides.
### 2. Caching with the Caching Module's Service
You can also use the Caching Module's service directly to cache custom data in your Medusa application.
For example, resolve the Caching Module's service in a workflow step and use its methods to cache brand information:
export const cachingHighlights = [
["14", "computeKey", "Compute the cache key."],
["15", "get", "Retrieve the cached value for the `brand` tag."],
["19", "cachedValue", "If a cached value exists, return it."],
["23", "getBrand", "Fetch the brand data if not cached."],
["25", "set", "Cache the fetched brand data with the `brand` tag."]
]
```ts highlights={cachingHighlights}
import { Modules } from "@medusajs/framework/utils"
import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
type StepInput = {
filters: Record<string, unknown>
}
export const getBrandStep = createStep(
"get-brand-step",
async (input: StepInput, { container }) => {
const cachingModuleService = container.resolve(Modules.CACHING)
const brandModuleService = container.resolve("brand")
const cacheKey = await cachingModuleService.computeKey(input.filters)
const cachedValue = await cachingModuleService.get({
tags: ["brand"]
})
if (cachedValue) {
return new StepResponse(cachedValue)
}
const brand = await brandModuleService.getBrand(input.filters)
await cachingModuleService.set({
key: cacheKey,
tags: [`Brand:${brand.id}`],
data: brand
})
return new StepResponse(brand)
}
)
```
In the example above, you create a step that resolves the Caching Module's service from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
Then, you use the `get` method of the service to retrieve a cached value with the tag `"brand"`. You can also use other methods such as `set` to cache a value and `clear` to remove a cached value.
Learn about other methods and options of the Caching Module in the [Use Caching Module](/references/caching-service) guide.
### Which Caching Method Should You Use?
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
Caching Method
</Table.HeaderCell>
<Table.HeaderCell>
When to Use
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
Query or Index Module
</Table.Cell>
<Table.Cell>
Ideal for standard data retrieval scenarios, such as fetching products or custom data.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
Caching Module's Service
</Table.Cell>
<Table.Cell>
Suitable for caching computed values, external API responses, or to control caching behavior.
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
Caching data with Query or the Index Module is ideal when retrieving standard data, such as products or custom entities. The Caching Module automatically handles cache keys and invalidation for you.
If you need to cache custom data like computed values or external API responses, or you want finer control over caching behavior, use the Caching Module's service directly. In this case, you must manage cache keys yourself, though you can still enable automatic invalidation using the service's `set` method.
---
## Caching Module Options
You can pass the following options to the Caching Module when registering it in your `medusa-config.ts` file:
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
Option
</Table.HeaderCell>
<Table.HeaderCell>
Description
</Table.HeaderCell>
<Table.HeaderCell>
Default
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`ttl`
</Table.Cell>
<Table.Cell>
A number indicating the default time-to-live (TTL) in seconds for cached items. After this period, cached items will be removed from the cache.
This number is passed to the underlying caching provider if no TTL is specified when caching data.
</Table.Cell>
<Table.Cell>
`3600` (1 hour)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`providers`
</Table.Cell>
<Table.Cell>
An array of caching providers to use. This allows you to configure multiple caching providers for different use cases.
</Table.Cell>
<Table.Cell>
No providers by default
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Caching Concepts
To learn more about caching concepts such as cache keys, cache tags, and automatic cache invalidation, refer to the [Caching Module Concepts guide](./concepts/page.mdx).

157
www/apps/resources/app/infrastructure-modules/caching/providers/page.mdx Normal file
View File

@@ -0,0 +1,157 @@
import { CardList, Card, Table, CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Caching Module Providers`,
}
# {metadata.title}
In this guide, you'll learn about Caching Module Providers in Medusa, including how to configure and use them in your Medusa application.
## What is a Caching Module Provider?
A Caching Module Provider implements the logic for caching data, such as integrating third-party caching services. The [Caching Module](../page.mdx) then uses the registered Caching Module Providers to handle caching data.
Medusa provides the [Redis Caching Module Provider](./redis/page.mdx) that you can use in development and production. You can also [Create a Caching Provider](/references/caching-module-provider).
<CardList
items={[
{
title: "Redis",
href: "/infrastructure-modules/caching/providers/redis",
badge: {
variant: "green",
children: "For Production"
}
},
{
title: "Memcached",
href: "/infrastructure-modules/caching/guides/memcached",
badge: {
variant: "blue",
children: "Tutorial"
}
}
]}
/>
---
## Default Caching Module Provider
You can register multiple Caching Module Providers and specify which one to use as the default. The Caching Module uses the default provider for all caching operations unless you specify a specific provider.
### How is the Default Provider Selected?
The Caching Module determines the default Caching Module Provider based on the following scenarios:
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Scenario</Table.HeaderCell>
<Table.HeaderCell>Default Provider</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
One provider is registered.
</Table.Cell>
<Table.Cell>
The registered provider.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
Multiple providers and one of them has an `is_default` flag.
</Table.Cell>
<Table.Cell>
The provider with the `is_default` flag set to `true`.
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
If none of the above scenarios apply, the Caching Module throws an error during startup indicating that no default provider is configured.
### Setting the Default Caching Module Provider
To specify a provider as the default, you can set its `is_default` option to `true` when registering it in the `provider` array of the Caching Module.
For example:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/caching",
options: {
providers: [
{
id: "caching-redis",
resolve: "@medusajs/caching-redis",
is_default: true, // Set as the default provider
options: {
// Redis options...
},
},
{
id: "caching-memcached",
resolve: "./path/to/your/memcached-provider",
options: {
// Memcached options...
},
}
]
}
}
]
})
```
In this example, the Redis Caching Module Provider is set as the default provider by setting `is_default: true`. The Memcached Caching Module Provider is also registered but not set as the default.
---
## Caching with Specific Providers
Whether you're caching data with Query, the Index Module, or directly using the Caching Module's service, you can specify an array of provider IDs to use for that specific caching operation.
For example, considering you have the [above configuration](../page.mdx#setting-the-default-caching-module-provider) with both Redis and Memcached providers registered, you can specify which provider to use when caching data:
<CodeTabs group="caching-method">
<CodeTab label="Query / Index Module" value="query-index">
```ts highlights={[["7"]]}
const { data: products } = useQueryGraphStep({
entity: "product",
fields: ["id", "title"],
options: {
cache: {
enable: true,
providers: ["caching-memcached"] // Specify Memcached provider
},
},
})
```
</CodeTab>
<CodeTab label="Caching Module Service" value="caching-service">
```ts highlights={[["6"]]}
const cachingModuleService = container.resolve(Modules.CACHING)
await cachingModuleService.set({
key: "product-list",
data: products,
providers: ["caching-memcached"] // Specify Memcached provider
})
```
</CodeTab>
</CodeTabs>
In this example, both Query and the Caching Module's service use the Memcached provider, overriding the default Redis provider.
The ID you pass is the same ID you specified in `medusa-config.ts` when registering the provider.

198
www/apps/resources/app/infrastructure-modules/caching/providers/redis/page.mdx Normal file
View File

@@ -0,0 +1,198 @@
import { Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `Redis Caching Module Provider`,
}
# {metadata.title}
The Redis Caching Module Provider is a robust caching solution that leverages [Redis](https://redis.io/) to store cached data. Redis offers high performance, scalability, and data persistence, making it an ideal choice for production environments.
<Note>
The Caching Module and its providers are available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
</Note>
---
## Register the Redis Caching Module
<Prerequisites items={[
{
text: "Redis installed and Redis server running",
link: "https://redis.io/docs/getting-started/installation/"
}
]} />
To use the Redis Caching Module Provider, you need to register it in the `providers` array of the Caching Module in your `medusa-config.ts`.
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/caching",
options: {
providers: [
{
resolve: "@medusajs/caching-redis",
id: "caching-redis",
// Optional, makes this the default caching provider
is_default: true,
options: {
redisUrl: process.env.CACHE_REDIS_URL,
// more options...
},
},
// other caching providers...
],
},
},
],
})
```
Notice that you pass an `id` property to the provider. The provider will be registered with that ID, which you can use to explicitly [specify the provider when caching data](../page.mdx#how-to-use-the-caching-module).
### Environment Variables
Make sure to add the following environment variable:
```bash
CACHE_REDIS_URL=redis://localhost:6379
```
### Redis Caching Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>
Option
</Table.HeaderCell>
<Table.HeaderCell>
Description
</Table.HeaderCell>
<Table.HeaderCell>
Default
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`redisUrl`
</Table.Cell>
<Table.Cell>
The connection URL for the Redis server.
</Table.Cell>
<Table.Cell>
Required. An error is thrown if not provided.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`ttl`
</Table.Cell>
<Table.Cell>
A number indicating the default time-to-live (TTL) in seconds for cached items. After this period, cached items will be removed from the cache.
</Table.Cell>
<Table.Cell>
`3600` (1 hour)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`prefix`
</Table.Cell>
<Table.Cell>
A string to prefix all cache keys with. This is useful for namespacing your cache keys, especially when sharing a Redis instance with other applications or modules.
</Table.Cell>
<Table.Cell>
No prefix by default
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`compressionThreshold`
</Table.Cell>
<Table.Cell>
A number indicating the size threshold in bytes above which cached items will be compressed before being stored in Redis. This helps save memory when caching large items.
</Table.Cell>
<Table.Cell>
`1024` (1 KB)
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Test the Redis Caching Module
You can test the Redis Caching Module by caching data using the Query or Index Module, or by directly using the Caching Module's service, as described in the [Caching Module guide](../page.mdx#how-to-use-the-caching-module).
If you don't set the Redis Caching Module Provider as the default, you can explicitly specify its provider ID `caching-redis` when caching data with Query, the Index Module, or directly with the Caching Module's service.
<Note title="Tip">
`caching-redis` is the ID you set in the `medusa-config.ts` file when registering the Redis Caching Module Provider.
</Note>
For example, you can create a workflow in `src/workflows/cache-products.ts` that caches products using the Redis Caching Module Provider:
```ts title="src/workflows/cache-products.ts" highlights={[["14"], ["15"], ["16"], ["17"]]}
import {
createWorkflow,
WorkflowResponse
} from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
export const cacheProductsWorkflow = createWorkflow(
"cache-products",
() => {
const { data: products } = useQueryGraphStep({
entity: "product",
fields: ["id", "title"],
options: {
cache: {
enable: true,
providers: ["caching-redis"],
},
},
})
return new WorkflowResponse(products)
}
)
```
Next, execute that workflow in an [API route](!docs!/learn/fundamentals/api-routes). For example, create a route at `src/api/cache-product/route.ts` with the following content:
```ts title="src/api/cache-product/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { cacheProductsWorkflow } from "../../workflows/cache-products"
export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
const { result } = await cacheProductsWorkflow(req.scope)
.run({})
res.status(200).json(result)
}
```
Finally, start your Medusa server with the following command:
```bash npm2yarn
npm run dev
```
Then, make a `GET` request to the `/cache-product` endpoint:
```bash
curl http://localhost:9000/cache-product
```
You should receive a response with the list of products. The first time you make this request, the products will be fetched from the database and cached in Redis. Subsequent requests will retrieve the products from the cache, resulting in improved performance.

2
www/apps/resources/app/infrastructure-modules/file/page.mdx
View File

@@ -60,7 +60,7 @@ Then, you use the `retrieveFile` method of the File Module to retrieve the URL o
---
### What is a File Module Provider?
## What is a File Module Provider?
A File Module Provider implements the underlying logic of handling uploads and downloads of assets, such as integrating third-party services. The File Module then uses the registered File Module Provider to handle file operations.

31
www/apps/resources/app/infrastructure-modules/page.mdx
View File

@@ -47,29 +47,36 @@ The Analytics Module exposes functionalities to track and analyze user interacti
## Cache Module
## Caching Module
A Cache Module is used to cache the results of computations such as price selection or various tax calculations. Learn more in [this documentation](./cache/page.mdx).
The Caching Module provides functionality to cache data in your Medusa application, improving performance and reducing latency for frequently accessed data.
The following Cache modules are provided by Medusa. You can also create your own cache module as explained in [this guide](./cache/create/page.mdx).
The following Caching modules are provided by Medusa. You can also create a custom Caching Module Provider as explained in the [Create Caching Module Provider guide](#).
<Note>
The Caching Module is available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). It replaces the deprecated [Cache Module](./cache/page.mdx).
</Note>
<CardList
items={[
{
title: "In-Memory",
href: "/infrastructure-modules/cache/in-memory",
badge: {
variant: "neutral",
children: "For Development"
}
},
{
title: "Redis",
href: "/infrastructure-modules/cache/redis",
href: "/infrastructure-modules/caching/providers/redis",
badge: {
variant: "green",
children: "For Production"
}
},
{
title: "Memcached",
// TODO add link
href: "#",
badge: {
variant: "blue",
children: "Tutorial"
}
}
]}
/>

6
www/apps/resources/app/sitemap.ts
View File

@@ -37,6 +37,12 @@ export default function sitemap(): MetadataRoute.Sitemap {
{
url: `${config.baseUrl}${basePathUrl("/references/cache-service")}`,
},
{
url: `${config.baseUrl}${basePathUrl("/references/caching-module-provider")}`,
},
{
url: `${config.baseUrl}${basePathUrl("/references/caching-service")}`,
},
{
url: `${config.baseUrl}${basePathUrl("/references/file-service")}`,
},

1
www/apps/resources/generated/edit-dates.mjs
View File

@@ -6622,5 +6622,6 @@ export const generatedEditDates = {
"app/data-model-repository-reference/methods/upsertWithReplace/page.mdx": "2025-10-09T11:44:53.535Z",
"app/how-to-tutorials/tutorials/agentic-commerce/page.mdx": "2025-10-09T11:25:48.831Z",
"app/storefront-development/production-optimizations/page.mdx": "2025-10-03T13:28:37.909Z",
"app/infrastructure-modules/caching/page.mdx": "2025-10-13T11:46:36.452Z",
"app/troubleshooting/subscribers/not-working/page.mdx": "2025-10-16T09:25:57.376Z"
}

36
www/apps/resources/generated/files-map.mjs
View File

@@ -831,6 +831,30 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/infrastructure-modules/cache/redis/page.mdx",
"pathname": "/infrastructure-modules/cache/redis"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/caching/concepts/page.mdx",
"pathname": "/infrastructure-modules/caching/concepts"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/caching/guides/memcached/page.mdx",
"pathname": "/infrastructure-modules/caching/guides/memcached"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/caching/migrate-cache/page.mdx",
"pathname": "/infrastructure-modules/caching/migrate-cache"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/caching/page.mdx",
"pathname": "/infrastructure-modules/caching"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/caching/providers/page.mdx",
"pathname": "/infrastructure-modules/caching/providers"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/caching/providers/redis/page.mdx",
"pathname": "/infrastructure-modules/caching/providers/redis"
},
{
"filePath": "/www/apps/resources/app/infrastructure-modules/event/create/page.mdx",
"pathname": "/infrastructure-modules/event/create"
@@ -1931,6 +1955,14 @@ export const filesMap = [
"filePath": "/www/apps/resources/references/cache/interfaces/cache.ICacheService/page.mdx",
"pathname": "/references/cache/interfaces/cache.ICacheService"
},
{
"filePath": "/www/apps/resources/references/caching/interfaces/caching.ICachingModuleService/page.mdx",
"pathname": "/references/caching/interfaces/caching.ICachingModuleService"
},
{
"filePath": "/www/apps/resources/references/caching/interfaces/caching.ICachingProviderService/page.mdx",
"pathname": "/references/caching/interfaces/caching.ICachingProviderService"
},
{
"filePath": "/www/apps/resources/references/cart/IBigNumber/methods/cart.IBigNumber.toJSON/page.mdx",
"pathname": "/references/cart/IBigNumber/methods/cart.IBigNumber.toJSON"
@@ -14187,6 +14219,10 @@ export const filesMap = [
"filePath": "/www/apps/resources/references/modules/cache/page.mdx",
"pathname": "/references/modules/cache"
},
{
"filePath": "/www/apps/resources/references/modules/caching/page.mdx",
"pathname": "/references/modules/caching"
},
{
"filePath": "/www/apps/resources/references/modules/cart/page.mdx",
"pathname": "/references/modules/cart"

16
www/apps/resources/generated/generated-how-to-tutorials-sidebar.mjs
View File

@@ -62,6 +62,14 @@ const generatedgeneratedHowToTutorialsSidebarSidebar = {
"path": "https://docs.medusajs.com/resources/infrastructure-modules/cache/create",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "ref",
"title": "Create Caching Provider",
"path": "https://docs.medusajs.com/resources/references/caching-module-provider",
"children": []
},
{
"loaded": true,
"isPathHref": true,
@@ -190,6 +198,14 @@ const generatedgeneratedHowToTutorialsSidebarSidebar = {
"path": "https://docs.medusajs.com/resources/references/cache-service",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "ref",
"title": "Use Caching Module",
"path": "https://docs.medusajs.com/resources/references/caching-service",
"children": []
},
{
"loaded": true,
"isPathHref": true,

88
www/apps/resources/generated/generated-infrastructure-modules-sidebar.mjs
View File

@@ -90,8 +90,94 @@ const generatedgeneratedInfrastructureModulesSidebarSidebar = {
"loaded": true,
"isPathHref": true,
"type": "category",
"title": "Cache Module",
"title": "Caching Module",
"initialOpen": true,
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/infrastructure-modules/caching",
"title": "Overview",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/infrastructure-modules/caching/concepts",
"title": "Concepts",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/infrastructure-modules/caching/migrate-cache",
"title": "Migrate from Cache Module",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"title": "Providers",
"path": "/infrastructure-modules/caching/providers",
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/infrastructure-modules/caching/providers/redis",
"title": "Redis",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/infrastructure-modules/caching/guides/memcached",
"title": "Memcached",
"children": []
}
]
},
{
"loaded": true,
"isPathHref": true,
"type": "sub-category",
"title": "Guides",
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/references/caching-module-provider",
"title": "Create Caching Module Provider",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/references/caching-service",
"title": "Use Caching Module",
"children": []
}
]
}
]
},
{
"loaded": true,
"isPathHref": true,
"type": "category",
"title": "Cache Module",
"initialOpen": false,
"badge": {
"variant": "neutral",
"text": "Deprecated"
},
"children": [
{
"loaded": true,

10
www/apps/resources/generated/slug-changes.mjs
View File

@@ -164,6 +164,16 @@ export const slugChanges = [
"newSlug": "/references/cache-service",
"filePath": "/www/apps/resources/references/cache/interfaces/cache.ICacheService/page.mdx"
},
{
"origSlug": "/references/caching/interfaces/caching.ICachingModuleService",
"newSlug": "/references/caching-service",
"filePath": "/www/apps/resources/references/caching/interfaces/caching.ICachingModuleService/page.mdx"
},
{
"origSlug": "/references/caching/interfaces/caching.ICachingProviderService",
"newSlug": "/references/caching-module-provider",
"filePath": "/www/apps/resources/references/caching/interfaces/caching.ICachingProviderService/page.mdx"
},
{
"origSlug": "/references/cart/ICartModuleService/methods/cart.ICartModuleService.addLineItemAdjustments",
"newSlug": "/references/cart/addLineItemAdjustments",

1
www/apps/resources/references/_index.mdx
View File

@@ -12,6 +12,7 @@ import { TypeList } from "docs-ui"
- [auth-models](modules/auth_models/page.mdx)
- [auth-provider](modules/auth_provider/page.mdx)
- [cache](modules/cache/page.mdx)
- [caching](modules/caching/page.mdx)
- [cart](modules/cart/page.mdx)
- [cart-models](modules/cart_models/page.mdx)
- [core-flows](modules/core_flows/page.mdx)

7
www/apps/resources/references/cache/interfaces/cache.ICacheService/page.mdx vendored
View File

@@ -17,6 +17,13 @@ import { TypeList } from "docs-ui"
In this document, you’ll learn about the different methods in the Cache Module's service and how to use them.
:::note[Deprecation Notice]
The Cache Module is deprecated starting from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). [Use the Caching Module](#) instead.
:::
---
## Resolve Cache Module's Service

295
www/apps/resources/references/caching/interfaces/caching.ICachingModuleService/page.mdx Normal file
View File

@@ -0,0 +1,295 @@
---
slug: /references/caching-service
tags:
- caching
- server
- how to
sidebar_label: Use Caching Module
---
import { TypeList } from "docs-ui"
# How to Use Caching Module
In this guide, you’ll learn about the different methods in the Caching Module's service and how to use them.
:::note
The Caching Module and its providers are available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
:::
:::tip
You should use the Caching Module's service when you're caching computed data or data from external APIs. To cache database query results, enable caching in [Query](!docs!/learn/fundamentals/module-links/query#cache) or [Index Module](!docs!/learn/fundamentals/module-links/index-module#cache) instead.
:::
---
## Resolve Caching Module's Service
In your workflow's step, you can resolve the Caching Module's service from the Medusa container:
```ts
import { Modules } from "@medusajs/framework/utils"
import { createStep } from "@medusajs/framework/workflows-sdk"
const step1 = createStep(
"step-1",
async ({}, { container }) => {
const cachingModuleService = container.resolve(
Modules.CACHING
)
// TODO use cachingModuleService
}
)
```
You can then use the Caching Module's service's methods in the step. The rest of this guide details these methods.
---
## clear
This method clears data from the cache. If neither `key` nor `tags` are provided, nothing is cleared.
By default, all items matching the key or tags are cleared regardless of their options. If you provide `options.autoInvalidate: true`,
only items that were set with `options.autoInvalidate: true` are cleared.
For example, if you set `options.autoInvalidate: true`, only items that were set with `options.autoInvalidate: true` are cleared.
Items that were set with `options.autoInvalidate: false` are only cleared when you don't provide any options.
### Example
To invalidate cache by key:
```ts
await cacheModuleService.clear({
key: "products" // this key would typically be a hash
})
```
This example will clear the item with the key `products` regardless of its `options.autoInvalidate` value.
To invalidate cache by tags:
```ts
await cacheModuleService.clear({
tags: ["Product:list:*"]
})
```
This example will clear all items with the tag `Product:list:*` regardless of their `options.autoInvalidate` value.
To invalidate only the cache data that were set to automatically invalidate:
```ts
await cacheModuleService.clear({
tags: ["Product:list:*"],
options: { autoInvalidate: true }
})
```
This example will only clear items with the tag `Product:list:*` that were set with `options.autoInvalidate: true`.
Items that were set with `options.autoInvalidate: false` will not be cleared.
:::note
Setting `options.autoInvalidate: false` when calling the `clear` method will not clear any items.
To clear items that were set with `options.autoInvalidate: false`, you must call the `clear` method without any options.
:::
To invalidate cache from specific providers:
```ts
await cacheModuleService.clear({
key: "products",
providers: ["caching-redis", "caching-memcached"]
})
```
This example will try to clear the data from both the `caching-redis` and `caching-memcached` providers.
### Parameters
<TypeList types={[{"name":"param0","type":"`object`","description":"The options for clearing the item(s).","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"key","type":"`string`","description":"The key of the item to clear.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tags","type":"`string`[]","description":"The tags of the items to clear. Tags\nare useful to clear multiple related items at once.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`object`","description":"Options for clearing the item(s). The options are matched against the stored options when the item was set.\nFor example, if the item was set with `autoInvalidate: true`, it will only be cleared if the `autoInvalidate` option is also set to `true`.\nIf not provided, all items matching the key or tags are cleared regardless of their options.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"autoInvalidate","type":"`boolean`","description":"Whether to clear item(s) that were set to automatically invalidate.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"providers","type":"`string`[]","description":"The providers from which to clear the item(s). You can specify an array of provider IDs.\nIf not provided, the [default provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider) is used.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clear"/>
### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;void&#62;","optional":false,"defaultValue":"","description":"A promise that resolves when the item(s) have been cleared.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clear"/>
___
## computeKey
This method computes a cache key based on the input object. It's useful to generate consistent and unique keys for caching.
### Example
```ts
const key = await cacheModuleService.computeKey({
id: "prod_123",
title: "Product 123"
})
// key will be a hash string like "a1b2c3d4e5f6g7h8i9j0"
```
### Parameters
<TypeList types={[{"name":"input","type":"`object`","description":"The input object to compute the key from.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeKey"/>
### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;string&#62;","optional":false,"defaultValue":"","description":"The computed cache key.","expandable":false,"children":[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeKey"/>
___
## computeTags
This method computes cache tags based on the input object. It's useful to generate consistent and relevant tags for caching.
### Example
```ts
const tags = await cacheModuleService.computeTags({
products: [{ id: "prod_123" }, { id: "prod_456" }],
}, {
operation: "updated"
})
// tags might be ["Product:prod_123", "Product:prod_456", "Product:list:*"]
```
### Parameters
<TypeList types={[{"name":"input","type":"`object`","description":"The input object to compute the tags from.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`Record<string, any>`","description":"Additional options to influence tag computation.","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeTags"/>
### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;string[]&#62;","optional":false,"defaultValue":"","description":"An array of computed cache tags.","expandable":false,"children":[{"name":"string[]","type":"`string`[]","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="computeTags"/>
___
## get
This method retrieves data from the cache. If neither `key` nor `tags` are provided, or the item is not found, `null` is returned.
### Example
To retrieve by key:
```ts
const data = await cacheModuleService.get({
key: "products", // this key would typically be a hash
}) as { id: string; title: string; }
```
To retrieve by tags:
```ts
const data = await cacheModuleService.get({
tags: ["Product:list:*"],
}) as { id: string; title: string; }[]
```
To retrieve by key from specific providers:
```ts
const data = await cacheModuleService.get({
key: "products", // this key would typically be a hash
providers: ["caching-redis", "caching-memcached"]
}) as { id: string; title: string; }
```
This example will try to get the data from the `caching-redis` provider first, and if not found, it will try to get it from the `caching-memcached` provider.
### Type Parameters
<TypeList types={[{"name":"T","type":"`object`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="get"/>
### Parameters
<TypeList types={[{"name":"param0","type":"`object`","description":"The options for retrieving the item.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"key","type":"`string`","description":"The key of the item to retrieve.\nIf both `key` and `tags` are provided, `key` takes precedence over `tags`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tags","type":"`string`[]","description":"The tags of the items to retrieve. Tags\nare useful to retrieve multiple related items at once.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"providers","type":"`string`[]","description":"The providers to retrieve the item(s) from. You can specify an array of provider IDs.\nThey're checked in the order they're provided in, so make sure to order them based on your priority.\nIf not provided, the [default provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider) is used.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="get"/>
### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;null \\| T&#62;","optional":false,"defaultValue":"","description":"The item(s) that was stored in the cache. If no item was found, or neither `key` nor `tags` were provided, `null` is returned.","expandable":false,"children":[{"name":"null \\| T","type":"`null` \\| T","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="get"/>
___
## set
This method stores data in the cache using the
[default Caching Module Provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider).
### Example
To store with key:
```ts
const data = { id: "prod_123", title: "Product 123" }
const key = await cacheModuleService.computeKey(data)
await cacheModuleService.set({
key,
data
})
```
To store with tags:
:::note
Tags should follow [conventions](https://docs.medusajs.com/infrastructure-modules/caching/concepts#caching-tags-convention) to ensure they're automatically invalidated.
:::
```ts
const data = [{ id: "prod_123", title: "Product 123" }]
const key = await cacheModuleService.computeKey(data)
await cacheModuleService.set({
key,
data,
tags: [`Product:${data[0].id}`, "Product:list:*"]
})
```
To disable auto-invalidation for the item:
```ts
const data = [{ id: "prod_123", title: "Product 123" }]
const key = await cacheModuleService.computeKey(data)
await cacheModuleService.set({
key,
data,
options: { autoInvalidate: false }
})
```
The item is now only invalidated when calling the `clear` method directly with the same key or tags.
To store with specific providers:
```ts
const data = { id: "prod_123", title: "Product 123" }
const key = await cacheModuleService.computeKey(data)
await cacheModuleService.set({
key,
data,
providers: [
"caching-redis",
{ id: "caching-memcached", ttl: 120 } // custom TTL for this provider
]
})
```
This example will store the item in both the `caching-redis` and `caching-memcached` providers, with a custom TTL of `120` seconds for the `caching-memcached` provider.
### Parameters
<TypeList types={[{"name":"param0","type":"`object`","description":"The options for storing the item.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"key","type":"`string`","description":"The key of the item to store.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`object`","description":"The data to store in the cache.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"ttl","type":"`number`","description":"The time-to-live (TTL in seconds) value in seconds.\nIf not provided, the default TTL value configured in the provider should be used.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tags","type":"`string`[]","description":"The tags of the items to store. Tags are useful to group related items \ntogether for retrieval or invalidation.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`object`","description":"Options for storing the item. The options are stored with the item, allowing you to later match against them when clearing the item.\nFor example, if you set `autoInvalidate: false`, the item will only be invalidated when calling the `clear` method directly with the same key or tags.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"autoInvalidate","type":"`boolean`","description":"Whether to automatically invalidate the item when related data changes.","optional":true,"defaultValue":"true","expandable":false,"children":[]}]},{"name":"providers","type":"`Providers`","description":"The providers to store the item(s) in. You can specify an array of provider IDs or an array of objects with provider ID and TTL.\nIf not provided, the [default provider](https://docs.medusajs.com/infrastructure-modules/caching/providers#default-caching-module-provider) is used.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;void&#62;","optional":false,"defaultValue":"","description":"A promise that resolves when the item has been stored.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>

333
www/apps/resources/references/caching/interfaces/caching.ICachingProviderService/page.mdx Normal file
View File

@@ -0,0 +1,333 @@
---
slug: /references/caching-module-provider
tags:
- caching
- server
- how to
sidebar_label: Create Caching Provider
keywords:
- caching
- provider
- integration
---
import { TypeList } from "docs-ui"
# How to Create a Caching Module Provider
In this guide, you’ll learn how to create a Caching Module Provider and the methods you must implement in its main service.
:::note
The Caching Module and its providers are available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
:::
---
## Implementation Example
As you implement your Caching Module Provider, it can be useful to refer to an existing provider and how it's implemeted.
If you need to refer to an existing implementation as an example, check the [Redis Caching Module Provider in the Medusa repository](https://github.com/medusajs/medusa/tree/develop/packages/modules/providers/caching-redis).
---
## 1. Create Module Provider Directory
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-caching`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-caching`.
<Note>
The rest of this guide always uses the `src/modules/my-caching` directory as an example.
</Note>
---
## 2. Create the Caching Module Provider Service
Create the file `src/modules/my-caching/service.ts` that holds the module provider's main service. It must implement the `ICachingProviderService` interface imported from `@medusajs/framework/types`:
```ts title="src/modules/my-caching/service.ts"
import { ICachingProviderService } from "@medusajs/framework/types"
class MyCachingProviderService implements ICachingProviderService {
// TODO implement methods
}
export default MyCachingProviderService
```
### constructor
The constructor allows you to access resources from the module's container using the first parameter,
and the module's options using the second parameter.
If you're creating a client or establishing a connection with a third-party service, do it in a [Loader](https://docs.medusajs.com/learn/fundamentals/modules/loaders)
and store it in the Module's container. Then, you can access it in your service using the container.
:::note[Loader Example]
[Initialize MongoDB client in loader and access it in service](https://docs.medusajs.com/learn/fundamentals/modules/loaders#example-register-custom-mongodb-connection).
:::
#### Example
```ts
import { ICachingProviderService } from "@medusajs/framework/types"
import { Logger } from "@medusajs/framework/types"
type InjectedDependencies = {
logger: Logger
// assuming you initialized a client
// in a Loader and stored it in the container
client: Client
}
type Options = {
url: string
}
class MyCachingModuleProvider implements ICachingProviderService {
static identifier = "my-cache"
protected logger_: Logger
protected options_: Options
protected client
constructor (
{ logger, client }: InjectedDependencies,
options: Options
) {
this.logger_ = logger
this.options_ = options
// set the service's client to
// the client from the container
this.client = client
}
// ...
}
export default MyCachingModuleProvider
```
### Identifier
Every caching module provider must have an `identifier` static property. The provider's ID
will be stored as `lp_{identifier}_{id}`, where `id` is the ID you set in your `medusa-config.ts` file.
For example:
```ts
class MyCachingModuleProvider implements ICachingProviderService {
static identifier = "my-cache"
// ...
}
```
### clear
This method clears data from the cache. If no options are specified, all items matching the key or tags should be cleared.
Otherwise, if `options.autoInvalidate` is `true`, only items that were set with `options.autoInvalidate: true` should be cleared.
Items with `options.autoInvalidate: false` should only be cleared when no options are provided.
If neither `key` nor `tags` are provided, nothing should be cleared.
#### Example
```ts
async clear({ key, tags, options, }: {
key?: string;
tags?: string[];
options?: { autoInvalidate?: boolean }
}): Promise<void> {
if (!options) {
// clear all items
await this.client.invalidate({ key, tags })
} else if (options.autoInvalidate) {
// clear only items with autoInvalidate option set to true
const keysToDelete: string[] = []
const storedOptions = await this.client.get({ key, tags, pipeline: "options" })
storedOptions.forEach((item) => {
if (item.autoInvalidate) {
keysToDelete.push(item.key as string)
}
})
await this.client.invalidate({ keys: keysToDelete })
}
}
```
#### Parameters
<TypeList types={[{"name":"param0","type":"`object`","description":"The parameters for clearing the item(s).","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"key","type":"`string`","description":"The key of the item to clear.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tags","type":"`string`[]","description":"The tags of the items to clear. All items with any of the provided tags should be cleared.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`object`","description":"Options for clearing the item(s). The options should be matched against the stored options when the item was set.\nFor example, if the item was set with `autoInvalidate: true`, it will only be cleared if the `autoInvalidate` option is also set to `true`.\nIf not provided, all items matching the key or tags should be cleared regardless of their options.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"autoInvalidate","type":"`boolean`","description":"Whether to clear item(s) that were set to automatically invalidate.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clear"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;void&#62;","optional":false,"defaultValue":"","description":"A promise that resolves when the item(s) have been cleared.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clear"/>
### get
This method retrieves data from the cache either by `key` or `tags`. If neither `key` nor `tags` are provided, `null` should be returned.
If both `key` and `tags` are provided, `key` should take precedence over `tags`.
#### Example
```ts
class MyCachingModuleProvider implements ICachingProviderService {
// ...
async get({ key, tags }: { key?: string; tags?: string[] }): Promise<any> {
// Assuming you're using a client to get data
if (key) {
return await this.client.get({ key })
}
if (tags) {
return await this.client.getByTags({ tags })
}
return null
}
}
```
#### Parameters
<TypeList types={[{"name":"param0","type":"`object`","description":"The parameters for retrieving the item.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"key","type":"`string`","description":"The key of the item to retrieve. If both are provided, `key` should take precedence over `tags`.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tags","type":"`string`[]","description":"The tags of the items to retrieve. All items with any of the provided tags should be retrieved.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="get"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;any&#62;","optional":false,"defaultValue":"","description":"The item(s) that was stored in the cache, or `null` if not found.","expandable":false,"children":[{"name":"any","type":"`any`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="get"/>
### set
This method stores data in the cache. It should also store the options with the item,
allowing you to later to check the `autoInvalidate` option when clearing the item.
#### Example
```ts
class MyCachingModuleProvider implements ICachingProviderService {
// ...
async set({ key, data, ttl, tags, options }: {
key: string;
data: any;
ttl?: number;
tags?: string[];
options?: { autoInvalidate?: boolean }
}): Promise<void> {
// Assuming you're using a client to set data
await this.client.set({ key, data, ttl, tags })
await this.client.set({ key, data: options, pipeline: "options" })
}
}
```
#### Parameters
<TypeList types={[{"name":"param0","type":"`object`","description":"The parameters for storing the item.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"key","type":"`string`","description":"The key of the item to store.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"data","type":"`object`","description":"The data to store in the cache.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"ttl","type":"`number`","description":"The time-to-live (TTL in seconds) value in seconds.\nIf not provided, the default TTL value configured in the provider should be used.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tags","type":"`string`[]","description":"The tags of the items to store. Items should be grouped together using tags for retrieval or invalidation.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`object`","description":"Options for storing the item. The options should be stored with the item, allowing you to later match against them when clearing the item.\nFor example, if you set `autoInvalidate: false`, the item will only be invalidated when calling the `clear` method directly with the same key or tags.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"autoInvalidate","type":"`boolean`","description":"Whether to automatically invalidate the item when related data changes.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
#### Returns
<TypeList types={[{"name":"Promise","type":"Promise&#60;void&#62;","optional":false,"defaultValue":"","description":"A promise that resolves when the item has been stored.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="set"/>
---
## 3. Create Module Definition File
Create the file `src/modules/my-caching/index.ts` with the following content:
```ts title="src/modules/my-caching/index.ts"
import { ModuleProvider, Modules } from "@medusajs/framework/utils"
import MyCachingProviderService from "./service"
export default ModuleProvider(Modules.CACHING, {
services: [MyCachingProviderService],
})
```
This exports the module provider's definition, indicating that the `MyCachingProviderService` is the module provider's service.
---
## 4. Use Module Provider
To use your Caching Module Provider, add it to the `providers` array of the Caching Module in `medusa-config.ts`:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/caching",
options: {
providers: [
{
// if module provider is in a plugin, use `plugin-name/providers/my-caching`
resolve: "./src/modules/my-caching",
id: "my-caching",
// set this if you want this provider to be used by default
// and you have other Caching Module Providers registered.
is_default: true,
options: {
url: "http://example.com",
// provider options...
}
},
]
}
}
]
})
```
---
## 5. Test it Out
To test out your Caching Module Provider, create a simple API route that retrieves cached data with Query:
```ts title="src/api/test-caching/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
const query = req.scope.resolve("query")
const { data } = await query.graph({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
providers: ["my-caching"], // use your provider id here
}
})
res.status(200).json({ data })
}
```
Then, start your Medusa server with the following command:
```bash npm2yarn
npm run dev
```
Next, send a `GET` request to `http://localhost:9000/test-caching`:
```bash
curl http://localhost:9000/test-caching
```
You will receive a response with the list of products. The first time you make this request, the products will be fetched from the database and cached in memory. Subsequent requests will retrieve the products from the cache, which improves performance.
---
## Useful Guides
- [How to Use Caching Module](/references/caching-service)

8
www/apps/resources/references/modules/caching/page.mdx Normal file
View File

@@ -0,0 +1,8 @@
import { TypeList } from "docs-ui"
# caching
## Interfaces
- [ICachingModuleService](../../caching/interfaces/caching.ICachingModuleService/page.mdx)
- [ICachingProviderService](../../caching/interfaces/caching.ICachingProviderService/page.mdx)

61
www/apps/resources/sidebars/infrastructure-modules.mjs
View File

@@ -59,8 +59,67 @@ export const infrastructureModulesSidebar = [
},
{
type: "category",
title: "Cache Module",
title: "Caching Module",
initialOpen: true,
children: [
{
type: "link",
path: "/infrastructure-modules/caching",
title: "Overview",
},
{
type: "link",
path: "/infrastructure-modules/caching/concepts",
title: "Concepts",
},
{
type: "link",
path: "/infrastructure-modules/caching/migrate-cache",
title: "Migrate from Cache Module",
},
{
type: "link",
title: "Providers",
path: "/infrastructure-modules/caching/providers",
children: [
{
type: "link",
path: "/infrastructure-modules/caching/providers/redis",
title: "Redis",
},
{
type: "link",
path: "/infrastructure-modules/caching/guides/memcached",
title: "Memcached",
},
],
},
{
type: "sub-category",
title: "Guides",
children: [
{
type: "link",
path: "/references/caching-module-provider",
title: "Create Caching Module Provider",
},
{
type: "link",
path: "/references/caching-service",
title: "Use Caching Module",
},
],
},
],
},
{
type: "category",
title: "Cache Module",
initialOpen: false,
badge: {
variant: "neutral",
text: "Deprecated",
},
children: [
{
type: "link",

2
www/apps/resources/utils/get-sidebar-for-path.ts
View File

@@ -77,6 +77,8 @@ const sidebarMappings: {
"/references/cache-service",
"/references/file-service",
"/references/analytics",
"/references/caching-service",
"/references/caching-module-provider",
],
},
{

6
www/eslint.config.mjs
View File

@@ -121,9 +121,7 @@ export default [
allow: ["error", "warn"],
}],
"react/prop-types": [2, {
ignore: ["className"],
}],
"react/prop-types": "off",
},
}, ...compat.extends("plugin:@typescript-eslint/recommended", "plugin:react/recommended").map(config => ({
...config,
@@ -162,6 +160,8 @@ export default [
"@/space-infix-ops": "error",
"@typescript-eslint/no-explicit-any": "warn",
"@typescript-eslint/no-unused-vars": "warn",
"react/prop-types": "off",
},
settings: {
next: {

32
www/packages/docs-ui/src/components/TypeList/Items/index.tsx
View File

@@ -9,6 +9,7 @@ import {
FeatureFlagNotice,
InlineCode,
MarkdownContent,
MDXComponents,
} from "@/components"
import clsx from "clsx"
import { Type, CommonProps as ParentCommonProps } from ".."
@@ -136,9 +137,36 @@ const TypeListItem = ({
<>
{item.description && (
<MarkdownContent
allowedElements={["a", "strong", "code", "ul", "ol", "li"]}
allowedElements={[
"a",
"strong",
"code",
"ul",
"ol",
"li",
"br",
]}
unwrapDisallowed={true}
className="text-medium"
components={{
...MDXComponents,
ol: (props: React.HTMLAttributes<HTMLElement>) => (
// @ts-expect-error Not recognized as a JSX element
<MDXComponents.ol
{...props}
className={clsx(props.className, "mt-docs_1.5")}
/>
),
li: (props: React.HTMLAttributes<HTMLElement>) => (
// @ts-expect-error Not recognized as a JSX element
<MDXComponents.li
{...props}
className={clsx(
props.className,
"!text-medusa-fg-subtle"
)}
/>
),
}}
>
{item.description}
</MarkdownContent>

4
www/packages/docs-ui/src/constants.tsx
View File

@@ -185,8 +185,8 @@ export const navDropdownItems: NavigationItem[] = [
},
{
type: "link",
title: "Cache",
link: "/resources/infrastructure-modules/cache",
title: "Caching",
link: "/resources/infrastructure-modules/caching",
},
{
type: "link",

10
www/packages/tags/src/tags/caching.ts Normal file
View File

@@ -0,0 +1,10 @@
export const caching = [
{
"title": "Use Caching Module",
"path": "https://docs.medusajs.com/resources/references/caching-service"
},
{
"title": "Create Caching Provider",
"path": "https://docs.medusajs.com/resources/references/caching-module-provider"
}
]

8
www/packages/tags/src/tags/how-to.ts
View File

@@ -59,6 +59,14 @@ export const howTo = [
"title": "Use Cache Module",
"path": "https://docs.medusajs.com/resources/references/cache-service"
},
{
"title": "Use Caching Module",
"path": "https://docs.medusajs.com/resources/references/caching-service"
},
{
"title": "Create Caching Provider",
"path": "https://docs.medusajs.com/resources/references/caching-module-provider"
},
{
"title": "Use Event Module",
"path": "https://docs.medusajs.com/resources/references/event-service"

1
www/packages/tags/src/tags/index.ts
View File

@@ -3,6 +3,7 @@ export * from "./analytics.js"
export * from "./api-key.js"
export * from "./auth.js"
export * from "./cache.js"
export * from "./caching.js"
export * from "./cart.js"
export * from "./checkout.js"
export * from "./concept.js"

8
www/packages/tags/src/tags/server.ts
View File

@@ -171,6 +171,14 @@ export const server = [
"title": "Use Cache Module",
"path": "https://docs.medusajs.com/resources/references/cache-service"
},
{
"title": "Use Caching Module",
"path": "https://docs.medusajs.com/resources/references/caching-service"
},
{
"title": "Create Caching Provider",
"path": "https://docs.medusajs.com/resources/references/caching-module-provider"
},
{
"title": "Use Event Module",
"path": "https://docs.medusajs.com/resources/references/event-service"

82
www/utils/generated/typedoc-json-output/cache.json
View File

@@ -1,19 +1,19 @@
{
"id": 61101,
"id": 0,
"name": "cache",
"variant": "project",
"kind": 1,
"flags": {},
"children": [
{
"id": 61102,
"id": 1,
"name": "ICacheService",
"variant": "declaration",
"kind": 256,
"flags": {},
"children": [
{
"id": 61103,
"id": 2,
"name": "get",
"variant": "declaration",
"kind": 2048,
@@ -23,12 +23,12 @@
"fileName": "service.ts",
"line": 11,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L11"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L11"
}
],
"signatures": [
{
"id": 61104,
"id": 3,
"name": "get",
"variant": "signature",
"kind": 4096,
@@ -66,12 +66,12 @@
"fileName": "service.ts",
"line": 11,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L11"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L11"
}
],
"typeParameters": [
{
"id": 61105,
"id": 4,
"name": "T",
"variant": "typeParam",
"kind": 131072,
@@ -80,7 +80,7 @@
],
"parameters": [
{
"id": 61106,
"id": 5,
"name": "key",
"variant": "param",
"kind": 32768,
@@ -115,7 +115,7 @@
},
{
"type": "reference",
"target": 61105,
"target": 4,
"name": "T",
"package": "@medusajs/types",
"refersToTypeParameter": true
@@ -130,7 +130,7 @@
]
},
{
"id": 61107,
"id": 6,
"name": "set",
"variant": "declaration",
"kind": 2048,
@@ -140,12 +140,12 @@
"fileName": "service.ts",
"line": 22,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L22"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L22"
}
],
"signatures": [
{
"id": 61108,
"id": 7,
"name": "set",
"variant": "signature",
"kind": 4096,
@@ -174,12 +174,12 @@
"fileName": "service.ts",
"line": 22,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L22"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L22"
}
],
"parameters": [
{
"id": 61109,
"id": 8,
"name": "key",
"variant": "param",
"kind": 32768,
@@ -198,7 +198,7 @@
}
},
{
"id": 61110,
"id": 9,
"name": "data",
"variant": "param",
"kind": 32768,
@@ -217,7 +217,7 @@
}
},
{
"id": 61111,
"id": 10,
"name": "ttl",
"variant": "param",
"kind": 32768,
@@ -257,7 +257,7 @@
]
},
{
"id": 61112,
"id": 11,
"name": "invalidate",
"variant": "declaration",
"kind": 2048,
@@ -267,12 +267,12 @@
"fileName": "service.ts",
"line": 31,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L31"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L31"
}
],
"signatures": [
{
"id": 61113,
"id": 12,
"name": "invalidate",
"variant": "signature",
"kind": 4096,
@@ -301,12 +301,12 @@
"fileName": "service.ts",
"line": 31,
"character": 2,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L31"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L31"
}
],
"parameters": [
{
"id": 61114,
"id": 13,
"name": "key",
"variant": "param",
"kind": 32768,
@@ -348,9 +348,9 @@
{
"title": "Methods",
"children": [
61103,
61107,
61112
2,
6,
11
]
}
],
@@ -359,7 +359,7 @@
"fileName": "service.ts",
"line": 1,
"character": 17,
"url": "https://github.com/medusajs/medusa/blob/a503bbe5963f95710f599c466dfb2c3956914e06/packages/core/types/src/cache/service.ts#L1"
"url": "https://github.com/medusajs/medusa/blob/54cf8811af626df63b1b093561bd0337d1f786eb/packages/core/types/src/cache/service.ts#L1"
}
]
}
@@ -368,65 +368,65 @@
{
"title": "Interfaces",
"children": [
61102
1
]
}
],
"packageName": "@medusajs/types",
"symbolIdMap": {
"61101": {
"0": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": ""
},
"61102": {
"1": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService"
},
"61103": {
"2": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService.get"
},
"61104": {
"3": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService.get"
},
"61105": {
"4": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "T"
},
"61106": {
"5": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "key"
},
"61107": {
"6": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService.set"
},
"61108": {
"7": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService.set"
},
"61109": {
"8": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "key"
},
"61110": {
"9": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "data"
},
"61111": {
"10": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ttl"
},
"61112": {
"11": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService.invalidate"
},
"61113": {
"12": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "ICacheService.invalidate"
},
"61114": {
"13": {
"sourceFileName": "../../../../packages/core/types/src/cache/service.ts",
"qualifiedName": "key"
}
@@ -436,7 +436,7 @@
"1": "../../../../packages/core/types/src/cache/service.ts"
},
"reflections": {
"1": 61101
"1": 0
}
}
}

2942
www/utils/generated/typedoc-json-output/caching.json Normal file
View File

File diff suppressed because it is too large Load Diff

5
www/utils/packages/typedoc-generate-references/src/constants/custom-options.ts
View File

@@ -22,6 +22,11 @@ const customOptions: Record<string, Partial<TypeDocOptions>> = {
tsConfigName: "types.json",
name: "cache",
}),
caching: getOptions({
entryPointPath: "packages/core/types/src/caching/index.ts",
tsConfigName: "types.json",
name: "caching",
}),
"core-flows": getOptions({
entryPointPath: "packages/core/core-flows/src/index.ts",
tsConfigName: "core-flows.json",

9
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/cache.ts
View File

@@ -5,7 +5,14 @@ const cacheOptions: FormattingOptionsType = {
reflectionGroups: {
Constructors: false,
},
reflectionDescription: `In this document, you’ll learn about the different methods in the Cache Module's service and how to use them.`,
reflectionDescription: `In this document, you’ll learn about the different methods in the Cache Module's service and how to use them.
:::note[Deprecation Notice]
The Cache Module is deprecated starting from [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0). [Use the Caching Module](#) instead.
:::
`,
frontmatterData: {
slug: "/references/cache-service",
tags: ["cache", "server", "how to"],

215
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/caching.ts Normal file
View File

@@ -0,0 +1,215 @@
import { FormattingOptionsType } from "types"
import baseSectionsOptions from "../base-section-options.js"
const cachingOptions: FormattingOptionsType = {
"^caching/.*ICachingProviderService": {
reflectionGroups: {
Constructors: false,
},
reflectionDescription: `In this guide, you’ll learn how to create a Caching Module Provider and the methods you must implement in its main service.
:::note
The Caching Module and its providers are available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
:::`,
frontmatterData: {
slug: "/references/caching-module-provider",
tags: ["caching", "server", "how to"],
sidebar_label: "Create Caching Provider",
keywords: ["caching", "provider", "integration"],
},
reflectionTitle: {
fullReplacement: "How to Create a Caching Module Provider",
},
shouldIncrementAfterStartSections: true,
expandMembers: true,
expandProperties: true,
sortMembers: true,
sections: {
...baseSectionsOptions,
member_declaration_title: false,
reflection_typeParameters: false,
},
startSections: [
// TODO add link to memcached guide when available
`## Implementation Example
As you implement your Caching Module Provider, it can be useful to refer to an existing provider and how it's implemeted.
If you need to refer to an existing implementation as an example, check the [Redis Caching Module Provider in the Medusa repository](https://github.com/medusajs/medusa/tree/develop/packages/modules/providers/caching-redis).`,
`## 1. Create Module Provider Directory
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the \`src/modules\` directory. For example, \`src/modules/my-caching\`.
If you're creating the module provider in a plugin, create it under the \`src/providers\` directory. For example, \`src/providers/my-caching\`.
<Note>
The rest of this guide always uses the \`src/modules/my-caching\` directory as an example.
</Note>`,
`## 2. Create the Caching Module Provider Service
Create the file \`src/modules/my-caching/service.ts\` that holds the module provider's main service. It must implement the \`ICachingProviderService\` interface imported from \`@medusajs/framework/types\`:
\`\`\`ts title="src/modules/my-caching/service.ts"
import { ICachingProviderService } from "@medusajs/framework/types"
class MyCachingProviderService implements ICachingProviderService {
// TODO implement methods
}
export default MyCachingProviderService
\`\`\``,
],
endSections: [
`## 3. Create Module Definition File
Create the file \`src/modules/my-caching/index.ts\` with the following content:
\`\`\`ts title="src/modules/my-caching/index.ts"
import { ModuleProvider, Modules } from "@medusajs/framework/utils"
import MyCachingProviderService from "./service"
export default ModuleProvider(Modules.CACHING, {
services: [MyCachingProviderService],
})
\`\`\`
This exports the module provider's definition, indicating that the \`MyCachingProviderService\` is the module provider's service.`,
`## 4. Use Module Provider
To use your Caching Module Provider, add it to the \`providers\` array of the Caching Module in \`medusa-config.ts\`:
\`\`\`ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/caching",
options: {
providers: [
{
// if module provider is in a plugin, use \`plugin-name/providers/my-caching\`
resolve: "./src/modules/my-caching",
id: "my-caching",
// set this if you want this provider to be used by default
// and you have other Caching Module Providers registered.
is_default: true,
options: {
url: "http://example.com",
// provider options...
}
},
]
}
}
]
})
\`\`\`
`,
`## 5. Test it Out
To test out your Caching Module Provider, create a simple API route that retrieves cached data with Query:
\`\`\`ts title="src/api/test-caching/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
const query = req.scope.resolve("query")
const { data } = await query.graph({
entity: "product",
fields: ["id", "title"],
}, {
cache: {
enable: true,
providers: ["my-caching"], // use your provider id here
}
})
res.status(200).json({ data })
}
\`\`\`
Then, start your Medusa server with the following command:
\`\`\`bash npm2yarn
npm run dev
\`\`\`
Next, send a \`GET\` request to \`http://localhost:9000/test-caching\`:
\`\`\`bash
curl http://localhost:9000/test-caching
\`\`\`
You will receive a response with the list of products. The first time you make this request, the products will be fetched from the database and cached in memory. Subsequent requests will retrieve the products from the cache, which improves performance.
`,
`## Useful Guides
- [How to Use Caching Module](/references/caching-service)
`,
],
},
"^caching/.*ICachingModuleService": {
reflectionGroups: {
Constructors: false,
},
reflectionDescription: `In this guide, you’ll learn about the different methods in the Caching Module's service and how to use them.
:::note
The Caching Module and its providers are available starting [Medusa v2.11.0](https://github.com/medusajs/medusa/releases/tag/v2.11.0).
:::
:::tip
You should use the Caching Module's service when you're caching computed data or data from external APIs. To cache database query results, enable caching in [Query](!docs!/learn/fundamentals/module-links/query#cache) or [Index Module](!docs!/learn/fundamentals/module-links/index-module#cache) instead.
:::
`,
frontmatterData: {
slug: "/references/caching-service",
tags: ["caching", "server", "how to"],
sidebar_label: "Use Caching Module",
},
reflectionTitle: {
fullReplacement: "How to Use Caching Module",
},
expandMembers: true,
sortMembers: true,
startSections: [
`## Resolve Caching Module's Service
In your workflow's step, you can resolve the Caching Module's service from the Medusa container:
\`\`\`ts
import { Modules } from "@medusajs/framework/utils"
import { createStep } from "@medusajs/framework/workflows-sdk"
const step1 = createStep(
"step-1",
async ({}, { container }) => {
const cachingModuleService = container.resolve(
Modules.CACHING
)
// TODO use cachingModuleService
}
)
\`\`\`
You can then use the Caching Module's service's methods in the step. The rest of this guide details these methods.
---
`,
],
},
}
export default cachingOptions

2
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/index.ts
View File

@@ -1,5 +1,6 @@
import { FormattingOptionsType } from "types"
import authProviderOptions from "./auth-provider.js"
import cachingOptions from "./caching.js"
import fileOptions from "./file.js"
import fulfillmentProviderOptions from "./fulfillment-provider.js"
import helperStepsOptions from "./helper-steps.js"
@@ -25,6 +26,7 @@ const mergerCustomOptions: FormattingOptionsType = {
...analyticsProviderOptions,
...authProviderOptions,
...cacheOptions,
...cachingOptions,
...coreFlowsOptions,
...dmlOptions,
...eventOptions,

6
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/locking.ts
View File

@@ -6,7 +6,7 @@ const lockingOptions: FormattingOptionsType = {
reflectionGroups: {
Constructors: false,
},
reflectionDescription: `In this document, you’ll learn how to create a Locking Module Provider and the methods you must implement in its main service.`,
reflectionDescription: `In this guide, you’ll learn how to create a Locking Module Provider and the methods you must implement in its main service.`,
frontmatterData: {
slug: "/references/locking-module-provider",
tags: ["locking", "server", "how to"],
@@ -86,7 +86,7 @@ module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/payment",
resolve: "@medusajs/medusa/locking",
options: {
providers: [
{
@@ -130,7 +130,7 @@ The Locking Module will now use your provider to handle all locking operations.
reflectionGroups: {
Constructors: false,
},
reflectionDescription: `In this document, you’ll learn about the different methods in the Locking Module's service and how to use them.`,
reflectionDescription: `In this guide, you’ll learn about the different methods in the Locking Module's service and how to use them.`,
frontmatterData: {
slug: "/references/locking-service",
tags: ["locking", "server", "how to"],

1
www/utils/packages/typedoc-generate-references/src/constants/references.ts
View File

@@ -38,6 +38,7 @@ const allReferences = [
"workflows",
"locking",
"cache",
"caching",
"event",
"file-service",
"notification-service",