@medusajs/file-s3
Documentation | Website
Building blocks for digital commerce
S3 File Module Provider for Medusa: stores uploaded files in Amazon S3 or any S3-compatible storage, such as MinIO, DigitalOcean Spaces, Cloudflare R2, or Supabase Storage. Use it for file storage in production. It ships with @medusajs/medusa and is registered through the @medusajs/medusa/file-s3 path.
At a glance
| Package | @medusajs/file-s3 |
| Type | Module Provider (File Module) |
| Provider ID | s3 |
| Registered by default | No (on Medusa Cloud, yes, with id: "s3" and IAM role authentication) |
| Import from | @medusajs/medusa/file-s3 |
Features
- Public and private file uploads, with presigned download and upload URLs.
- Access key or IAM role authentication.
- Custom endpoints for S3-compatible storage.
- Configurable object ACLs, including disabling ACLs for buckets with Object Ownership set to "Bucket owner enforced".
Installation
No installation needed. The provider is a dependency of @medusajs/medusa.
Usage
Register the provider in the File Module's providers array in medusa-config.ts. The File Module accepts exactly one provider, so this replaces the default local provider.
import { defineConfig } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
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,
},
},
],
},
},
],
})
Configuration
| Option | Type | Description | Default |
|---|---|---|---|
file_url |
string |
Required. Base URL used to build public file URLs. | - |
region |
string |
Required. The bucket's region. | - |
bucket |
string |
Required. The bucket name. | - |
authentication_method |
"access-key" | "s3-iam-role" |
How to authenticate. With s3-iam-role, the AWS SDK's default credentials chain is used. |
"access-key" |
access_key_id |
string |
Access key ID. Required when authentication_method is "access-key". |
- |
secret_access_key |
string |
Secret access key. Required when authentication_method is "access-key". |
- |
session_token |
string |
Session token for temporary credentials. | - |
prefix |
string |
Prefix (folder path) added to uploaded file keys. | "" |
endpoint |
string |
Custom endpoint URL for S3-compatible storage. | - |
cache_control |
string |
Cache-Control header set on uploaded objects. |
"public, max-age=31536000" |
download_file_duration |
number |
Validity of presigned download URLs, in seconds. | 3600 |
additional_client_config |
Record<string, any> |
Extra options passed to the S3 client. | {} |
acl |
"public-read" | "private" | "authenticated-read" | "bucket-owner-full-control" | false |
ACL set on uploaded objects. false omits the ACL header. |
"public-read" for public files, "private" for private files |
| Environment variable | Description |
|---|---|
S3_FILE_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION, S3_BUCKET, S3_ENDPOINT |
Values for the matching options, as used in the example above. |
S3_FILE_URL, S3_PREFIX, S3_REGION, S3_BUCKET, S3_ENDPOINT |
Read by defineConfig to configure the default provider on Medusa Cloud. |