How to Create a File Provider Module

In this document, you’ll learn how to create a file provider module and the methods you must implement in its main service.

1. Create Module Directory#

Start by creating a new directory for your module. For example, src/modules/my-file.

2. Create the File Provider Service#

Create the file src/modules/my-file/service.ts that holds the implementation of the module's main service. It must extend the AbstractFileProviderService class imported from @medusajs/framework/utils:

src/modules/my-file/service.ts
1import { AbstractFileProviderService } from "@medusajs/framework/utils"2
3class MyFileProviderService extends AbstractFileProviderService {4  // TODO implement methods5}6
7export default MyFileProviderService

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 the constructor.

Example

Code
1import { Logger } from "@medusajs/framework/types"2import { AbstractFileProviderService } from "@medusajs/framework/utils"3
4type InjectedDependencies = {5  logger: Logger6}7
8type Options = {9  apiKey: string10}11
12class MyFileProviderService extends AbstractFileProviderService {13  protected logger_: Logger14  protected options_: Options15  static identifier = "my-file"16  // assuming you're initializing a client17  protected client18
19  constructor (20    { logger }: InjectedDependencies,21    options: Options22  ) {23    super()24
25    this.logger_ = logger26    this.options_ = options27
28    // assuming you're initializing a client29    this.client = new Client(options)30  }31}32
33export default MyFileProviderService

constructor#

validateOptions#

This method validates the options of the provider set in medusa-config.ts. Implementing this method is optional. It's useful if your provider requires custom validation.

If the options aren't valid, throw an error.

Example

Code
1class MyFileProviderService extends AbstractFileProviderService {2  static validateOptions(options: Record<any, any>) {3    if (!options.apiKey) {4      throw new MedusaError(5        MedusaError.Types.INVALID_DATA,6        "API key is required in the provider's options."7      )8    }9  }10}

Parameters

Returns

upload#

This method uploads a file using your provider's custom logic.

Example

Code
1class MyFileProviderService extends AbstractFileProviderService {2  // ...3  async upload(4    file: ProviderUploadFileDTO5  ): Promise<ProviderFileResultDTO> {6    // TODO upload file to third-party provider7    // or using custom logic8
9    return {10      url: "some-url.com",11      key: "file-name"12    }13  }14}

Parameters

Returns

delete#

This method deletes the file from storage.

Example

Code
1class MyFileProviderService extends AbstractFileProviderService {2  // ...3  async delete(file: ProviderDeleteFileDTO): Promise<void> {4    // TODO logic to remove the file from storage5    // Use the `file.fileKey` to delete the file6    // for example:7    this.client.delete(file.fileKey)8  }9}

Parameters

Returns

getPresignedDownloadUrl#

This method is used to retrieve a download URL of the file. For some providers, such as S3, a presigned URL indicates a temporary URL to get access to a file.

If your provider doesn’t perform or offer a similar functionality, you can return the URL to download the file.

Example

Code
1class MyFileProviderService extends AbstractFileProviderService {2  // ...3  async getPresignedDownloadUrl(4    fileData: ProviderGetFileDTO5  ): Promise<string> {6    // TODO logic to get the presigned URL7    // Use the `file.fileKey` to delete the file8    // for example:9    return this.client.getPresignedUrl(fileData.fileKey)10  }11}

Parameters

Returns

3. Create Module Definition File#

Create the file src/modules/my-file/index.ts with the following content:

src/modules/my-file/index.ts
1import MyFileProviderService from "./service"2import { 3  ModuleProvider, 4  Modules5} from "@medusajs/framework/utils"6
7export default ModuleProvider(Modules.FILE, {8  services: [MyFileProviderService],9})

This exports the module's definition, indicating that the MyFileProviderService is the module's service.

4. Use Module#

To use your File Module Provider, add it to the providers array of the File Module in medusa-config.ts:

medusa-config.ts
1import { Modules } from "@medusajs/framework/utils"2
3// ...4
5module.exports = defineConfig({6  // ...7  modules: [8    {9      resolve: "@medusajs/medusa/file",10      options: {11        providers: [12          {13            resolve: "./src/modules/my-file",14            id: "my-file",15            options: {16              // provider options...17            },18          },19        ],20      },21    },22  ]23})

5. Test it Out#

To test out your file provider, use the Medusa Admin or the Upload API route to upload a file.