Better Upload Documentation

For large files, use the multipart upload helpers to break the upload into parts. The workflow is:

1. createMultipartUpload: Initialize the upload and get an uploadId.
2. uploadPart: Upload individual chunks of data.
3. completeMultipartUpload: Finalize the upload by providing an array of partNumber and eTag pairs.
4. abortMultipartUpload: Cancel the upload if necessary.

import {
  createMultipartUpload,
  uploadPart,
  completeMultipartUpload,
  abortMultipartUpload
} from '@better-upload/server/helpers';

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

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

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

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

You can intercept various stages of the upload process by providing callback functions in the useUploadFile options object:

• onBeforeUpload: Called before requesting the pre-signed URL. Use this to modify the file (e.g., resizing, renaming) by returning a new File object, or throw an error to reject the upload.
• onUploadBegin: Called after the server responds with the pre-signed URL, but before the file starts uploading to S3.
• onUploadProgress: Called whenever the upload progress changes. Provides { file } where file.progress is a value between 0 and 1.
• onUploadComplete: Called after a successful upload.
• onError: Called if the upload fails or if inputs are invalid. Provides the error object.
• onUploadSettle: Called after the upload finishes, regardless of whether it succeeded or failed.

useUploadFile({
  route: 'profile',
  onBeforeUpload: ({ file }) => {
    // rename the file
    return new File([file], 'renamed-' + file.name, { type: file.type });
  },
  onUploadBegin: ({ file, metadata }) => {
    console.log('Upload begin');
  },
  onUploadProgress: ({ file }) => {
    console.log(`Upload progress: ${file.progress * 100}%`);
  },
  onUploadComplete: ({ file, metadata }) => {
    console.log('File uploaded');
  },
  onError: (error) => {
    console.log(error.message);
  },
  onUploadSettle: ({ file, metadata }) => {
    console.log('Upload settled');
  },
});

This guide demonstrates how to set up single file uploads in a React application using Better Upload. The process involves installing the server and client packages, configuring a server route to generate pre-signed S3 URLs, and using the @better-upload/client hooks with a pre-built UI component.

Prerequisites:

• An S3-compatible bucket (AWS S3, Cloudflare R2, etc.).
• A React framework (e.g., Next.js).

Steps:

1. Install dependencies:

   npm i @better-upload/server @better-upload/client

2. Set up the server: Configure a server route (e.g., profile) to generate pre-signed URLs for your S3 bucket.

3. Install UI components: Use the shadcn CLI to add the pre-built upload button:

   npx shadcn@latest add @better-upload/upload-button

4. Implement the Uploader component: Use the useUploadFile hook to connect your UI to the server route.

5. Configure CORS: Ensure your S3 bucket has the correct CORS configuration to allow requests from your application's domain.

'use client'; // only for Next.js

import { useUploadFile } from '@better-upload/client';
import { UploadButton } from '@/components/ui/upload-button';

export function Uploader() {
  const { control } = useUploadFile({
    route: 'profile',
  });

  return <UploadButton control={control} accept="image/*" />;
}

Configure your server-side upload route using @better-upload/server. In this example, we use the Next.js adapter and AWS client. The route configuration defines the constraints for the upload, such as multipleFiles, maxFiles, and maxFileSize. You can also use onBeforeUpload to customize the object key (e.g., adding a prefix like form/).

import { route, type Router } from '@better-upload/server';
import { toRouteHandler } from '@better-upload/server/adapters/next';
import { aws } from '@better-upload/server/clients';

const router: Router = {
  client: aws(),
  bucketName: 'my-bucket',
  routes: {
    form: route({
      multipleFiles: true,
      maxFiles: 5,
      maxFileSize: 1024 * 1024 * 5, // 5MB
      onBeforeUpload() {
        return {
          generateObjectInfo: ({ file }) => ({ key: `form/${file.name}` }),
        };
      },
    }),
  },
};

export const { POST } = toRouteHandler(router);