S3 File Module Provider

The S3 File Module Provider integrates Amazon S3 and services following a compatible API (such as MinIO or DigitalOcean Spaces) to store files uploaded to your Medusa application.


Prerequisites#

  • AWS account.
  • Create AWS user with AmazonS3FullAccess permissions.
  • Create AWS user access key ID and secret access key.
  • Create S3 bucket with the "Public Access setting" enabled:
    1. On your bucket's dashboard, click on the Permissions tab.
    2. Click on the Edit button of the Block public access (bucket settings) section.
    3. In the form that opens, don't toggle any checkboxes and click the "Save changes" button.
    4. Confirm saving the changes by entering confirm in the pop-up that shows.
    5. Back on the Permissions page, scroll to the Object Ownership section and click the Edit button.
    6. In the form that opens:
      • Choose the "ACLs enabled" card.
      • Click on the "Save changes" button.
    7. Back on the Permissions page, scroll to the "Access Control List (ACL)" section and click on the Edit button.
    8. In the form that opens, enable the Read permission for "Everyone (public access)".
    9. Check the "I understand the effects of these changes on my objects and buckets." checkbox.
    10. Click on the "Save changes" button.

Register the S3 File Module#

Add the module into the providers array of the File Module:

NoteThe File Module accepts one provider only.
medusa-config.ts
1import { Modules } from "@medusajs/framework/utils"2
3// ...4
5module.exports = {6  // ...7  modules: [8    // ...9    {10      resolve: "@medusajs/medusa/file",11      options: {12        providers: [13          {14            resolve: "@medusajs/medusa/file-s3",15            id: "s3",16            options: {17              file_url: process.env.S3_FILE_URL,18              access_key_id: process.env.S3_ACCESS_KEY_ID,19              secret_access_key: process.env.S3_SECRET_ACCESS_KEY,20              region: process.env.S3_REGION,21              bucket: process.env.S3_BUCKET,22              endpoint: process.env.S3_ENDPOINT,23              // other options...24            },25          },26        ],27      },28    },29  ]30}

S3 File Module Options#

OptionDescriptionDefault

file_url

The base URL to upload files to.

  • For AWS S3, the endpoint is of the format https://{bucket}.s3.{region}.amazonaws.com
  • For MinIO, it's the URL to the MinIO server with the bucket's name. For example, https://{server-domain}/{bucket}.
  • For DigitalOcean Spaces, it's either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
  • for Supabase, it's https://{uniqueID}.supabase.co/storage/v1/object/public/{bucket}. You can retrieve the uniqueID from Storage Settings page in the Endpoint URL.

-

access_key_id

The AWS or (S3 compatible) user's access key ID.

-

secret_access_key

The AWS or (S3 compatible) user's secret access key.

-

region

The bucket's region code.

For MinIO, use us-east-1.

-

bucket

The bucket's name.

-

endpoint

The URL to the AWS S3 (or compatible S3 API) server.

  • For AWS S3, the endpoint is of the format https://s3.{region}.amazonaws.com
  • For MinIO, it's the URL to the MinIO server.
  • For DigitalOcean Spaces, it's the Spaces Origin Endpoint.
  • For Supabase, it's the Endpoint URL in the Storage Settings.

-

prefix

A string to prefix each uploaded file's name.

-

cache_control

A string indicating how long objects remain in the AWS S3 (or compatible S3 API) cache.

public, max-age=31536000

download_file_duration

A number indicating the expiry time of presigned URLs in seconds.

3600 (An hour)

additional_client_config

Any additional configurations to pass to the S3 client.

Refer to this AWS API reference for a full list of accepted configuration.

-

Additional Configuration for MinIO and Supabase#

If you're using MinIO or Supabase, set forcePathStyle to true in the additional_client_config object.

For example:

medusa-config.ts
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/file",6      options: {7        providers: [8          {9            resolve: "@medusajs/medusa/file-s3",10            id: "s3",11            options: {12              // ...13              additional_client_config: {14                forcePathStyle: true,15              },16            },17          },18        ],19      },20    },21  ]22})

Troubleshooting#

AWS: The bucket does not allow ACLs (Enabling public access to bucket)
Was this page helpful?
Edit this page