Helpers

Server-side

Helpers for your router and server.

Client-side

Helpers for your frontend.

S3 Clients

Better Upload has built-in clients for popular S3-compatible storage services, like AWS S3 and Cloudflare R2. Suggest a new client by opening an issue.

import { aws } from '@better-upload/server/clients';

const s3 = aws({
  accessKeyId: 'your-access-key-id',
  secretAccessKey: 'your-secret-access-key',
  region: 'us-east-1',
});

You can omit the parameters and let the client get your credentials from environment variables.

Objects

Helpers for working with objects in S3-compatible storage services. Suggest new helpers by opening an issue.

Presign get object

Generate a pre-signed URL to download an object. Commonly used for client-side downloads.

import { presignGetObject } from '@better-upload/server/helpers';

const url = await presignGetObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
  expiresIn: 3600, // 1 hour
});

Get object

Get an object (including its content) from an S3 bucket.

import { getObject, getObjectStream } from '@better-upload/server/helpers';

// as a Blob
const object = await getObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

// as a ReadableStream
const objectStream = await getObjectStream(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

Head object

Get metadata about an object without fetching its content.

import { headObject } from '@better-upload/server/helpers';

const object = await headObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

Move object (rename)

Move an object from one key to another, within or between, S3 buckets. Also known as renaming.

import { moveObject } from '@better-upload/server/helpers';

await moveObject(s3, {
  source: {
    bucket: 'source-bucket',
    key: 'example.png',
  },
  destination: {
    bucket: 'destination-bucket',
    key: 'copy.png',
  },
});

This copies the object to the new location and then deletes the original object. It can be slow.

Copy object

Copy an object, within or between, S3 buckets.

import { copyObject } from '@better-upload/server/helpers';

await copyObject(s3, {
  source: {
    bucket: 'source-bucket',
    key: 'example.png',
  },
  destination: {
    bucket: 'destination-bucket',
    key: 'images/example.png',
  },
});

Put object

Upload an object to an S3 bucket.

import { putObject } from '@better-upload/server/helpers';

await putObject(s3, {
  bucket: 'my-bucket',
  key: 'example.txt',
  body: 'Hello, world!',
  contentType: 'text/plain',
});

Do not use this helper for large files or for client-side uploads (use the standard router instead).

Delete object

Delete an object from an S3 bucket.

import { deleteObject } from '@better-upload/server/helpers';

await deleteObject(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

Delete objects

Delete multiple objects from an S3 bucket in a single request.

import { deleteObjects } from '@better-upload/server/helpers';

const { deleted, errors } = await deleteObjects(s3, {
  bucket: 'my-bucket',
  objects: [{ key: 'file1.png' }, { key: 'file2.png' }],
});

Multipart uploads

Helpers for working with multipart uploads in S3-compatible storage services.

Create multipart upload

Create a new multipart upload in an S3 bucket.

import { createMultipartUpload } from '@better-upload/server/helpers';

const { uploadId } = await createMultipartUpload(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  contentType: 'application/zip',
});

Upload part

Upload a part of a multipart upload.

import { uploadPart } from '@better-upload/server/helpers';

const { eTag } = await uploadPart(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  uploadId: '...',
  partNumber: 1,
  body: partData,
});

Complete multipart upload

Complete a multipart upload in an S3 bucket.

import { completeMultipartUpload } from '@better-upload/server/helpers';

await completeMultipartUpload(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  uploadId: '...',
  parts: [
    { partNumber: 1, eTag: '...' },
    { partNumber: 2, eTag: '...' },
    // ...
  ],
});

Abort multipart upload

Abort a multipart upload in an S3 bucket.

import { abortMultipartUpload } from '@better-upload/server/helpers';

await abortMultipartUpload(s3, {
  bucket: 'my-bucket',
  key: 'large-file.zip',
  uploadId: '...',
});

Object tagging operations

Helpers for managing object tags in S3-compatible storage services.

Get object tagging

Get the tags of an S3 object.

import { getObjectTagging } from '@better-upload/server/helpers';

const { tags, tagsObject } = await getObjectTagging(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

Put object tagging

Set the tags for an S3 object.

import { putObjectTagging } from '@better-upload/server/helpers';

await putObjectTagging(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
  tagging: {
    tag1: 'value1',
    tag2: 'value2',
  },
});

Delete object tagging

Delete all tags from an S3 object.

import { deleteObjectTagging } from '@better-upload/server/helpers';

await deleteObjectTagging(s3, {
  bucket: 'my-bucket',
  key: 'example.png',
});

Server-side

Client-side

On this page