---
slug: /references/file-provider-module
keywords:
- file
- storage
- provider
- integration
---
import { TypeList } from "docs-ui"
# How to Create a File Module Provider
In this document, you’ll learn how to create a File Module Provider and the methods you must implement in its main service.
---
## Implementation Example
As you implement your File Module Provider, it can be useful to refer to an existing provider and how it's implemeted.
If you need to refer to an existing implementation as an example, check the [S3 File Module Provider in the Medusa repository](https://github.com/medusajs/medusa/tree/develop/packages/modules/providers/file-s3).
---
## Create Module Provider Directory
Start by creating a new directory for your module provider.
If you're creating the module provider in a Medusa application, create it under the `src/modules` directory. For example, `src/modules/my-file`.
If you're creating the module provider in a plugin, create it under the `src/providers` directory. For example, `src/providers/my-file`.
The rest of this guide always uses the `src/modules/my-file` directory as an example.
---
## 2. Create the File Module Provider's Service
Create the file `src/modules/my-file/service.ts` that holds the implementation of the module provider's main service. It must extend the `AbstractFileProviderService` class imported from `@medusajs/framework/utils`:
```ts title="src/modules/my-file/service.ts"
import { AbstractFileProviderService } from "@medusajs/framework/utils"
class MyFileProviderService extends AbstractFileProviderService {
// TODO implement methods
}
export 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
```ts
import { Logger } from "@medusajs/framework/types"
import { AbstractFileProviderService } from "@medusajs/framework/utils"
type InjectedDependencies = {
logger: Logger
}
type Options = {
apiKey: string
}
class MyFileProviderService extends AbstractFileProviderService {
protected logger_: Logger
protected options_: Options
static identifier = "my-file"
// assuming you're initializing a client
protected client
constructor (
{ logger }: InjectedDependencies,
options: Options
) {
super()
this.logger_ = logger
this.options_ = options
// assuming you're initializing a client
this.client = new Client(options)
}
}
export default MyFileProviderService
```
### identifier
Each file provider has a unique ID used to identify it. The provider's ID
will be stored as `fs_{identifier}_{id}`, where `{id}` is the provider's `id`
property in the `medusa-config.ts`.
#### Example
```ts
class MyFileProviderService extends AbstractFileProviderService {
static identifier = "my-file"
// ...
}
```
### delete
This method deletes one or more files from the storage. It's used when an admin user
deletes a product image, or other custom file deletions.
#### Example
```ts
class MyFileProviderService extends AbstractFileProviderService {
// ...
async delete(
files: FileTypes.ProviderDeleteFileDTO | FileTypes.ProviderDeleteFileDTO[]
): Promise {
// TODO logic to remove the file from storage
// Use the `file.fileKey` to delete the file, which is the identifier of the file
// in the provider's storage.
// for example:
const fileArray = Array.isArray(files) ? files : [files]
for (const file of fileArray) {
this.client.delete(file.fileKey)
}
}
}
```
#### Parameters
#### Returns
### getAsBuffer
This method retrieves an uploaded file as a buffer. This is useful when you want to
process the entire file in memory or send it as a response.
:::note
This is only available after Medusa `v2.8.0`.
:::
#### Example
```ts
class MyFileProviderService extends AbstractFileProviderService {
// ...
async getAsBuffer(file: ProviderDeleteFileDTO): Promise {
// TODO logic to get the file as a buffer
// Use the `file.fileKey` to get the file, which is the identifier of the file
// in the provider's storage.
// for example:
this.client.getAsBuffer(file.fileKey)
}
}
```
#### Parameters
#### Returns
### getDownloadStream
This method retrieves an uploaded file as a stream. This is useful when streaming
a file to clients or you want to process the file in chunks.
:::note
This is only available after Medusa `v2.8.0`.
:::
#### Example
```ts
class MyFileProviderService extends AbstractFileProviderService {
// ...
async getAsStream(file: ProviderDeleteFileDTO): Promise {
// TODO logic to get the file as a stream
// Use the `file.fileKey` to get the file, which is the identifier of the file
// in the provider's storage.
// for example:
this.client.getAsStream(file.fileKey)
}
}
```
#### 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
```ts
class MyFileProviderService extends AbstractFileProviderService {
// ...
async getPresignedDownloadUrl(
fileData: ProviderGetFileDTO
): Promise {
// TODO logic to get the presigned URL
// Use the `file.fileKey` to delete the file, which is the identifier of the file
// in the provider's storage.
// for example:
return this.client.getPresignedUrl(fileData.fileKey)
}
}
```
#### Parameters
#### Returns
### getPresignedUploadUrl
This method is used to get a presigned upload URL for a file. For some providers,
such as S3, a presigned URL indicates a temporary URL to get upload a file.
If your provider doesn’t perform or offer a similar functionality, you don't have to
implement this method. Instead, an error is thrown when the method is called.
#### Example
```ts
class MyFileProviderService extends AbstractFileProviderService {
// ...
async getPresignedUploadUrl(
fileData: ProviderGetPresignedUploadUrlDTO
): Promise {
// TODO logic to get the presigned upload URL
// for example:
return this.client.getPresignedUploadUrl(fileData.filename, fileData.mimeType)
}
}
```
#### Parameters
#### Returns
### upload
This method uploads a file using your provider's custom logic. In this method, you can upload the file
into your provider's storage, and return the uploaded file's details.
This method will be used when uploading product images, CSV files for imports, or other
custom file uploads.
#### Example
```ts
class MyFileProviderService extends AbstractFileProviderService {
// ...
async upload(
file: ProviderUploadFileDTO
): Promise {
// TODO upload file to third-party provider
// or using custom logic
// for example:
this.client.upload(file)
return {
url: "some-url.com",
key: "file-name-or-id"
}
}
}
```
#### Parameters
#### Returns
### 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
```ts
class MyFileProviderService extends AbstractFileProviderService {
static validateOptions(options: Record) {
if (!options.apiKey) {
throw new MedusaError(
MedusaError.Types.INVALID_DATA,
"API key is required in the provider's options."
)
}
}
}
```
#### Parameters
`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
---
## 3. Create Module Provider Definition File
Create the file `src/modules/my-file/index.ts` with the following content:
```ts title="src/modules/my-file/index.ts"
import MyFileProviderService from "./service"
import {
ModuleProvider,
Modules
} from "@medusajs/framework/utils"
export default ModuleProvider(Modules.FILE, {
services: [MyFileProviderService],
})
```
This exports the module provider's definition, indicating that the `MyFileProviderService` is the module provider's service.
---
## 4. Use Module Provider
To use your File Module Provider, add it to the `providers` array of the File Module in `medusa-config.ts`:
The File Module accepts one provider only.
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/file",
options: {
providers: [
// default provider
{
resolve: "@medusajs/medusa/file-local",
id: "local",
},
{
// if module provider is in a plugin, use `plugin-name/providers/my-file`
resolve: "./src/modules/my-file",
id: "my-file",
options: {
// provider options...
},
},
],
},
},
]
})
```
---
## 5. Test it Out
To test out your File Module Provider, use the Medusa Admin or the [Upload API route](https://docs.medusajs.com/v2/api/admin#uploads_postuploads) to upload a file.