Caching Module

In this guide, you'll learn about the Caching Module and its providers.

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 or Memcached. This provides flexibility in customizing your Medusa application's infrastructure to meet your performance and scalability requirements.

Caching Module vs Cache Module#

Before Medusa v2.11.0, you used the Cache Module 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.

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.

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:

Terminal
❯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:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/caching",6      options: {7        providers: [8          {9            resolve: "@medusajs/caching-redis",10            id: "caching-redis",11            // Optional, makes this the default caching provider12            is_default: true,13            options: {14              redisUrl: process.env.CACHE_REDIS_URL,15              // more options...16            },17          },18        ],19      },20    },21  ],22})

This registers the Caching Module in your application with the Redis Caching Module Provider.

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 to learn more about Caching Module Providers in Medusa, and how to configure the default provider.

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 or the Index Module, or by directly using the Caching Module's 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:

Code
1import {2  createWorkflow,3  WorkflowResponse,4} from "@medusajs/framework/workflows-sdk"5import { useQueryGraphStep } from "@medusajs/medusa/core-flows"6
7export const workflow = createWorkflow(8  "workflow-1",9  () => {10    const { data: products } = useQueryGraphStep({11      entity: "product",12      fields: ["id", "title"],13      options: {14        cache: {15          enable: true,16        },17      },18    })19
20    return new WorkflowResponse(products)21  }22)

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 and Index Module 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:

Code
1import { Modules } from "@medusajs/framework/utils"2import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"3
4type StepInput = {5  filters: Record<string, unknown>6}7
8export const getBrandStep = createStep(9  "get-brand-step",10  async (input: StepInput, { container }) => {11    const cachingModuleService = container.resolve(Modules.CACHING)12    const brandModuleService = container.resolve("brand")13
14    const cacheKey = await cachingModuleService.computeKey(input.filters)15    const cachedValue = await cachingModuleService.get({16      tags: ["brand"],17    })18
19    if (cachedValue) {20      return new StepResponse(cachedValue)21    }22
23    const brand = await brandModuleService.getBrand(input.filters)24
25    await cachingModuleService.set({26      key: cacheKey,27      tags: [`Brand:${brand.id}`],28      data: brand,29    })30
31    return new StepResponse(brand)32  }33)

In the example above, you create a step that resolves the Caching Module's service from the 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 guide.

Which Caching Method Should You Use?#

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:

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.