npm.io
2.22.7 • Published 4d ago

@medusajs/file-s3

Licence
MIT
Version
2.22.7
Deps
4
Size
36 kB
Vulns
0
Weekly
0
Stars
35.0K

Medusa logo

@medusajs/file-s3

Documentation | Website

Building blocks for digital commerce

Medusa is released under the MIT license. PRs welcome! Discord Chat Follow @medusajs

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.

Resources

Keywords