Help

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.

Looking for managed storage? Cloud offers a managed file storage solution with AWS S3 for your Medusa application. Refer to the S3 Cloud documentation for more details.

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:

Note: The File Module accepts one provider only.

medusa-config.ts
import { Modules } from "@medusajs/framework/utils"

// ...

module.exports = {
  // ...
  modules: [
    // ...
    {
      resolve: "@medusajs/medusa/file",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/file-s3",
            id: "s3",
            options: {
              file_url: process.env.S3_FILE_URL,
              access_key_id: process.env.S3_ACCESS_KEY_ID,
              secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
              region: process.env.S3_REGION,
              bucket: process.env.S3_BUCKET,
              endpoint: process.env.S3_ENDPOINT,
              // other options...
            },
          },
        ],
      },
    },
  ],
}

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
module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/file",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/file-s3",
            id: "s3",
            options: {
              // ...
              additional_client_config: {
                forcePathStyle: true,
              },
            },
          },
        ],
      },
    },
  ],
})

S3 File Module Options#

Option	Description	Default
`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}`. Locally, it may be something like `http://192.168.0.123:9001/{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. For Cloudflare R2, it's your `Custom Domain` (recommended for production use) or `Public R2.dev Bucket URL` (for development).	-
`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`. For Cloudflare, use `auto`.	-
`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 example, locally, it may be something like `http://192.168.0.123:9001`. For DigitalOcean Spaces, it's the Spaces Origin Endpoint of the format `https://{region}.digitaloceanspaces.com`. For Supabase, it's the Endpoint URL in the Storage Settings. For Cloudflare, it's the endpoint for S3 clients `https://{your-account-id}.r2.cloudflarestorage.com`.	-
`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.	-

Troubleshooting#

AWS: The bucket does not allow ACLs (Enabling public access to bucket)

Cloudflare: Checksum error

Was this page helpful?