AWS S3

You may use the S3 Driver to manage files using AWS S3. Make sure to install the following peer dependencies in your project.

npm i @aws-sdk/s3-request-presigner @aws-sdk/client-s3

Once done, you can create an instance of the S3 Driver and use it as follows.

import { Disk } from 'flydrive'
import { S3Driver } from 'flydrive/drivers/s3'

const disk = new Disk(
  new S3Driver({
    credentials: {
      accessKeyId: 'AWS_ACCESS_KEY_ID',
      secretAccessKey: 'AWS_SECRET_ACCESS_KEY',
    },
    region: 'AWS_REGION',
    bucket: 'S3_BUCKET',
    visibility: 'private',
  })
)

You can pass all the options accepted by the @aws-sdk/client-s3 package to the S3Driver along with the following/required options.

bucket

The bucket option defines the S3 bucket to use for managing files.

visibility

The visibility option specifies the ACL property of the object while writing it to the S3 bucket.

• The public visibility sets the ACL to public-read.
• The private visibility sets the ACL to private.

supportsACL

Specify if the cloud service supports per-object ACL. For example, Cloudflare R2 does not support per-object ACL and does not implement the ACL commands.

Therefore, you must set the supportsACL = false when using R2 or any other S3 compatible service that does not support ACL.

cdnUrl

The cdnUrl property can be used to define the base URL for generating public URL for a file. For example, If you use CloudFront alongside S3 to serve public files, the cdnUrl property should be the CloudFront URL.

urlBuilder

Define a custom URL builder for creating public and signed URLs. Learn more

Using an existing S3 client

If you already have an instance of S3Client from the @aws-sdk/client-s3 package. You may pass it directly to the Flydrive S3Driver as follows.

import { S3Driver } from 'flydrive/drivers/s3'
import { S3Client } from '@aws-sdk/client-s3'

const client = new S3Client({})

const driver = new S3Driver({
  client: client,
  bucket: 'S3_BUCKET',
  visibility: 'private',
})

Creating public URLs

Public URLs can be created for files uploaded to S3 with public visibility. The public URL can point to a CDN if you have configured the cdnUrl inside the driver config. Otherwise, it will fallback to virtual hosted-style AWS URL. For example:

const disk = new Disk(
  new S3Driver({
    cdnUrl: 'https://djs74oztd4h.cloudfront.net',
    bucket: 'testing-drive',
  })
)

const URL = await disk.getUrl('avatar.png')
console.log(URL) // https://djs74oztd4h.cloudfront.net/avatar.png

const disk = new Disk(
  new S3Driver({
    cdnUrl: 'https://djs74oztd4h.cloudfront.net',
    bucket: 'testing-drive',
  })
)

const URL = await disk.getUrl('avatar.png')
console.log(URL) // https://testing-drive.s3.amazonaws.com/avatar.png

You may also self create a public URL by defining a custom URL builder within the config. For example:

const disk = new Disk(
  new S3Driver({
    bucket: 'testing-drive',
    urlBuilder: {
      async generateURL(key, bucket, s3Client) {
        return `https://some-custom-url/files/${bucket}/${key}`
      },
    },
  })
)

const URL = await disk.getUrl('avatar.png')
console.log(URL) // https://some-custom-url/files/testing-drive/avatar.png

Creating signed URLs

Signed URLs are created to provide time-based access to a private file hosted on S3. For example:

const disk = new Disk(new S3Driver({}))

const signedURL = await disk.getSignedUrl('invoice.pdf', {
  expiresIn: '30mins',
})

At the time of generating the signed URL, you can pass one of the following options along with the options accepted by GetObjectCommand class.

await disk.getSignedUrl('invoice.pdf', {
  expiresIn: '30mins',
  contentType: 'application/pdf',
  contentDisposition: 'attachment',

  /**
   * Additional options applicable for S3 only
   */
  ResponseCacheControl: 'max-age=604800',
})