How to Create a Service

In this document, you’ll learn how you can create a Service and use it across your Medusa backend just like any of the core services.

Service Implementation

To create a service, create a TypeScript or JavaScript file in src/services to hold the service. The name of the file should be the name of the service without Service. This is essential as the file name is used when registering the service in the dependency container, and Service is appended to the camel-case version of the file name automatically.

For example, if you want to create a service helloService, create the file hello.ts in src/services with the following content:

/src/services/hello.ts

import { TransactionBaseService } from "@medusajs/medusa"
import { EntityManager } from "typeorm"

class HelloService extends TransactionBaseService {
  protected manager_: EntityManager
  protected transactionManager_: EntityManager
  getMessage() {
    return `Welcome to My Store!`
  }
}

export default HelloService

This service will be registered in the dependency container as helloService.

---

Service Life Time

As the dependency container in Medusa is built on top of awilix, you can specify the Lifetime of a service. The lifetime is added as a static property to the service.

There are three lifetime types:

1. Lifetime.TRANSIENT: when used, a new instance of the service is created everytime it is resolved in other resources from the dependency container.
2. Lifetime.SCOPED: (default for custom services) when used, an instance of the service is created and reused in the scope of the dependency container. So, when the service is resolved in other resources that share that dependency container, the same instance of the service will be returned.
3. Lifetime.SINGLETON: (default for core services) when used, the service is always reused, regardless of the scope. An instance of the service is cached in the root container.

You can set the lifetime of your service by setting the LIFE_TIME static property:

/src/services/hello.ts

import { TransactionBaseService } from "@medusajs/medusa"
import { Lifetime } from "awilix"

class HelloService extends TransactionBaseService {
  static LIFE_TIME = Lifetime.SCOPED

  // ...
}

---

Service Constructor

As the service extends the TransactionBaseService class, all services in Medusa’s core, as well as all your custom services, will be available in your service’s constructor using dependency injection.

So, if you want your service to use another service, simply add it as part of your constructor’s dependencies and set it to a field inside your service’s class:

class HelloService extends TransactionBaseService {
  private productService: ProductService

  constructor(container) {
    super(container)
    this.productService = container.productService
  }
  // ...
}

Then, you can use that service anywhere in your custom service:

class HelloService extends TransactionBaseService {
  // ...
  async getProductCount() {
    return await this.productService.count()
  }
}

---

Retrieve Medusa Configurations

Within your service, you may need to access the Medusa configuration exported from medusa-config.js. To do that, you can access configModule using dependency injection.

For example:

import {
  ConfigModule,
  TransactionBaseService,
} from "@medusajs/medusa"

type InjectedDependencies = {
  configModule: ConfigModule
}

class HelloService extends TransactionBaseService {
  protected readonly configModule_: ConfigModule

  constructor(container: InjectedDependencies) {
    super(container)
    this.configModule_ = container.configModule
  }

  getConfigurations() {
    return this.configModule_
  }

  // ...
}

export default HelloService

---

Use a Service

In this section, you'll learn how to use services throughout your Medusa backend. This includes both Medusa's services and your custom services.

Before using your service, make sure you run the build command:

• npm
• Yarn
• pnpm

npm run build

yarn build

pnpm run build

In a Service

To use your custom service in another custom service, you can have easy access to it in the dependencies injected to the constructor of your service:

class MyService extends TransactionBaseService {
  constructor(container) {
    super(container)
    this.helloService = container.helloService
  }
  // ...
}

In an Endpoint

To use your custom service in an endpoint, you can use req.scope.resolve passing it the service’s registration name:

const helloService = req.scope.resolve("helloService")

res.json({
  message: helloService.getMessage(),
})

In a Subscriber

To use your custom service in a subscriber, you can have easy access to it in the subscriber’s dependencies injected to the constructor of your subscriber:

class MySubscriber {
  constructor({ helloService, eventBusService }) {
    this.helloService = helloService
  }
  // ...
}

---

Troubleshooting

AwilixResolutionError: Could Not Resolve X

If you're registering a custom resource within a middleware, for example a logged-in user, then make sure that all services that are using it have their LIFE_TIME static property either set to Lifetime.SCOPED or Lifetime.TRANSIENT. This mainly applies for services in the core Medusa package, as, by default, their lifetime is Lifetime.SINGLETON.

For example:

import { Lifetime } from "awilix"
import { 
  ProductService as MedusaProductService,
} from "@medusajs/medusa"

// extending ProductService from the core
class ProductService extends MedusaProductService {
  // The default life time for a core service is SINGLETON
  static LIFE_TIME = Lifetime.SCOPED

  // ...
}

export default ProductService

This may require you to extend a service as explained in this documentation if necessary.

If you're unsure which service you need to change its LIFE_TIME property, it should be mentioned along with the AwilixResolutionError message. For example:

AwilixResolutionError: Could not resolve 'loggedInUser'.

Resolution path: cartService -> productService -> loggedInUser

As shown in the resolution path, you must change the LIFE_TIME property of both cartService and productService to Lifetime.SCOPED or Lifetime.TRANSIENT.

You can learn about the service lifetime in the Create a Service documentation.

---

See Also

• Create a Plugin