From 2cc42ca0ef9415d08ad21f72f48ccd1b70c220e4 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 26 Nov 2025 18:00:45 +0200 Subject: [PATCH] docs: add guide on clearing cache (#14133) * docs: add guide on clearing cache * update llms --- www/apps/book/public/llms-full.txt | 6 +- .../caching/guides/clear-cache/page.mdx | 73 +++++++++++++++++++ www/apps/resources/generated/edit-dates.mjs | 3 +- www/apps/resources/generated/files-map.mjs | 4 + ...nerated-infrastructure-modules-sidebar.mjs | 8 ++ .../sidebars/infrastructure-modules.mjs | 5 ++ 6 files changed, 95 insertions(+), 4 deletions(-) create mode 100644 www/apps/resources/app/infrastructure-modules/caching/guides/clear-cache/page.mdx diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index e2e7a1c939..ce91b3afa4 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -43027,11 +43027,11 @@ In this guide, you'll learn how to clear cached data in Medusa. ## Why Clear Cache? -You should mainly cache data that isn't frequently changing, such as product details or categories. However, there are scenarios where you might need to clear the cache. +You should mainly cache data that isn't frequently changing, such as product details or categories. However, there are scenarios where you might need to clear the cache of that data manually. -For example, if you've integrated a third-party system that updates product information outside of Medusa, or if you've cached data from the third-party system, Medusa won't be aware of these changes. +For example, if you've integrated a third-party system that updates product information outside of Medusa, or if you've cached data from the third-party system, Medusa won't be aware of changes made externally. -In such cases, clearing the cache ensures that Medusa fetches the most up-to-date information from the source rather than relying on outdated cached data. +In such cases, you should clear the cache in Medusa to ensure it fetches the most up-to-date information from the source rather than relying on outdated cached data. *** diff --git a/www/apps/resources/app/infrastructure-modules/caching/guides/clear-cache/page.mdx b/www/apps/resources/app/infrastructure-modules/caching/guides/clear-cache/page.mdx new file mode 100644 index 0000000000..329e0a26a3 --- /dev/null +++ b/www/apps/resources/app/infrastructure-modules/caching/guides/clear-cache/page.mdx @@ -0,0 +1,73 @@ +export const metadata = { + title: `How to Clear Cached Data`, +} + +# {metadata.title} + +In this guide, you'll learn how to clear cached data in Medusa. + +## Why Clear Cache? + +You should mainly cache data that isn't frequently changing, such as product details or categories. However, there are scenarios where you might need to clear the cache of that data manually. + +For example, if you've integrated a third-party system that updates product information outside of Medusa, or if you've cached data from the third-party system, Medusa won't be aware of changes made externally. + +In such cases, you should clear the cache in Medusa to ensure it fetches the most up-to-date information from the source rather than relying on outdated cached data. + +--- + +## How to Clear Cache + +This section explains how to clear data cached by the Caching Module in Medusa. + +### Identify Cache Tags + +Before clearing the cache, identify the specific cache tags associated with the data you want to clear. + +When you cache entities with the [Query](!docs!/learn/fundamentals/module-links/query) or [Index Module](!docs!/learn/fundamentals/module-links/index-module), the Caching Module automatically generates tags based on the entity type and its ID: + +- `Entity:id`: Cache tag for a single record of an entity. For example, `Product:prod_123` caches a single product with the ID `prod_123`. +- `Entity:list:*`: Cache tag for a list of records of an entity. For example, `Product:list:*` caches a list of products. + +To clear the cache for a specific product, use the `Product:{id}` tag. To clear the cache for all products, use the `Product:list:*` tag. + +Refer to the [Caching Module Concepts guide](../../concepts/page.mdx#caching-tags-convention) to learn more about cache tags. + +### Clear Cache with Caching Module Service + +To clear cached data, use the [clear](/references/caching-service#clear) method of the Caching Module's service. You can resolve the service in a workflow step, API route, subscriber, or scheduled job, then call the `clear` method with the identified cache tags. + +For example, to clear the cache for specific products in a workflow step: + +```ts +import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk" +import { Modules } from "@medusajs/framework/utils" + +type ClearProductCacheInput = { + productId: string | string[] +} + +export const clearProductCacheStep = createStep( + "clear-product-cache", + async ({ productId }: ClearProductCacheInput, { container }) => { + const cachingModuleService = container.resolve(Modules.CACHING) + + const productIds = Array.isArray(productId) ? productId : [productId] + + // Clear cache for all specified products + for (const id of productIds) { + if (id) { + await cachingModuleService.clear({ + tags: [`Product:${id}`], + }) + } + } + + return new StepResponse({}) + } +) +``` + +In this example, the `clearProductCacheStep` step takes a `productId` (or an array of IDs) as input and clears the cache for each specified product using its cache tag. + +You can then use this step in a workflow to clear the cache whenever necessary, such as after receiving a webhook from a third-party system indicating that product data has changed. diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 1b408e40e7..701d9b451c 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -6718,5 +6718,6 @@ export const generatedEditDates = { "references/core_flows/Product/Workflows_Product/functions/core_flows.Product.Workflows_Product.batchImageVariantsWorkflow/page.mdx": "2025-11-05T12:22:20.639Z", "references/core_flows/Product/Workflows_Product/functions/core_flows.Product.Workflows_Product.batchVariantImagesWorkflow/page.mdx": "2025-11-05T12:22:20.671Z", "app/storefront-development/guides/react-native-expo/page.mdx": "2025-11-06T07:18:45.347Z", - "app/how-to-tutorials/tutorials/customer-tiers/page.mdx": "2025-11-25T08:24:24.566Z" + "app/how-to-tutorials/tutorials/customer-tiers/page.mdx": "2025-11-25T08:24:24.566Z", + "app/infrastructure-modules/caching/guides/clear-cache/page.mdx": "2025-11-26T13:19:26.629Z" } \ No newline at end of file diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs index 1299253487..56158a813c 100644 --- a/www/apps/resources/generated/files-map.mjs +++ b/www/apps/resources/generated/files-map.mjs @@ -847,6 +847,10 @@ export const filesMap = [ "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/clear-cache/page.mdx", + "pathname": "/infrastructure-modules/caching/guides/clear-cache" + }, { "filePath": "/www/apps/resources/app/infrastructure-modules/caching/guides/memcached/page.mdx", "pathname": "/infrastructure-modules/caching/guides/memcached" diff --git a/www/apps/resources/generated/generated-infrastructure-modules-sidebar.mjs b/www/apps/resources/generated/generated-infrastructure-modules-sidebar.mjs index 6902ddfdc2..989d0d92ad 100644 --- a/www/apps/resources/generated/generated-infrastructure-modules-sidebar.mjs +++ b/www/apps/resources/generated/generated-infrastructure-modules-sidebar.mjs @@ -148,6 +148,14 @@ const generatedgeneratedInfrastructureModulesSidebarSidebar = { "type": "sub-category", "title": "Guides", "children": [ + { + "loaded": true, + "isPathHref": true, + "type": "link", + "path": "/infrastructure-modules/caching/guides/clear-cache", + "title": "Clear Cache", + "children": [] + }, { "loaded": true, "isPathHref": true, diff --git a/www/apps/resources/sidebars/infrastructure-modules.mjs b/www/apps/resources/sidebars/infrastructure-modules.mjs index 93387d5aa3..993944b987 100644 --- a/www/apps/resources/sidebars/infrastructure-modules.mjs +++ b/www/apps/resources/sidebars/infrastructure-modules.mjs @@ -98,6 +98,11 @@ export const infrastructureModulesSidebar = [ type: "sub-category", title: "Guides", children: [ + { + type: "link", + path: "/infrastructure-modules/caching/guides/clear-cache", + title: "Clear Cache", + }, { type: "link", path: "/references/caching-module-provider",