How to Extend a Repository

In this document, you’ll learn how to extend a core repository in Medusa.

Overview

Medusa uses Typeorm’s Repositories to perform operations on an entity, such as retrieve or update the entity. Typeorm already provides these basic functionalities within a repository, but sometimes you need to implement a custom implementation to handle the logic behind these operations differently. You might also want to add custom methods related to processing entities that aren’t available in the default repositories.

In this guide, you’ll learn how to extend a repository in the core Medusa package. This guide will use the Product repository as an example to demonstrate the steps.

Word of Caution about Overriding

Extending repositories to add new methods shouldn't cause any issues within your commerce application. However, if you extend them to override their existing methods, you should be aware that this could have negative implications, such as unanticipated bugs, especially when you try to upgrade the core Medusa package to a newer version.

---

Step 1: Create Repository File

In your Medusa backend, create the file src/repositories/product.ts. This file will hold your extended repository.

Note that the name of the file must be the same as the name of the original repository in the core package. Since in this guide you’re extending the Product repository, it’s named product to match the core. If you’re extending the customer repository, for example, the file should be named customer.ts.

---

Step 2: Implement Extended Repository

In the file you created, you must retrieve both the repository you're extending along with its entity from the core. You’ll then use the data source exported from the core package to extend the repository.

Tip

A data source is Typeorm’s connection settings that allows you to connect to your database. You can learn more about it in Typeorm’s documentation.

Here’s an example of the implementation of the extended Product repository:

src/repositories/product.ts

import { Product } from "@medusajs/medusa"
import { 
  dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
  // alias the core repository to not cause a naming conflict
  ProductRepository as MedusaProductRepository,
} from "@medusajs/medusa/dist/repositories/product"

export const ProductRepository = dataSource
  .getRepository(Product)
  .extend({
    // it is important to spread the existing repository here.
    //  Otherwise you will end up losing core properties
    ...Object.assign(MedusaProductRepository, {
      target: Product,
    }),

    /**
     * Here you can create your custom function
     * For example
     */
    customFunction(): void {
      // TODO add custom implementation
      return
    },
  })

export default ProductRepository

You first import all necessary resources from the core package: the Product entity, the dataSource instance, and the core’s ProductRepository aliased as MedusaProductRepository to avoid naming conflict.

You then use the dataSource instance to retrieve the Product entity’s repository and extend it using the repository’s extend method. This method is available as part of Typeorm Repository API. This method returns your extended repository.

The extend method accepts an object with all the methods to add to the extended repository.

You must first add the properties of the repository you’re extending, which in this case is the product repository (aliased as MedusaProductRepository). This will ensure you don’t lose core methods, which can lead to the core not working as expected. You add use the spread operator (…) with the MedusaProductRepository to spread its properties.

After that, you can add your custom methods to the repository. In the example above, you add the method customFunction. You can use any name for your methods.

---

Step 3: Use Your Extended Repository

You can now use your extended repository in other resources such as services or API Routes.

Here’s an example of using it in an API Route:

src/api/store/custom/route.ts

import type { 
  MedusaRequest, 
  MedusaResponse,
} from "@medusajs/medusa"
import ProductRepository from "./path/to/product.ts"
import { EntityManager } from "typeorm"

export const GET = async (
  req: MedusaRequest, 
  res: MedusaResponse
) => {
  // ...

  const productRepository: typeof ProductRepository = 
  req.scope.resolve(
    "productRepository"
  )
  const manager: EntityManager = req.scope.resolve("manager")
  const productRepo = manager.withRepository(
    productRepository
  )
  productRepo.customFunction()

  // ...
}

---

Step 4: Test Your Implementation

For changes to take effect, you must transpile your code by running the build command in the root of the Medusa backend:

• npm
• Yarn
• pnpm

npm run build

yarn build

pnpm run build

Then, run the following command to start your backend:

• npm
• Yarn
• pnpm

npx medusa develop

npx medusa develop

npx medusa develop

You should see your custom implementation working as expected.