Mastering File Upload and Download in Next.js - A Comprehensive Guide with Cloudflare R2 Bucket (S3-Compatible)

[
  {
    "AllowedOrigins": [
      "http://localhost:3000",
      "http://localhost:3001",
      "https://assets.grahamquan.com"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "HEAD",
      "DELETE"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [
      "ETag"    <--- this for multi part large file upload
    ],
    "MaxAgeSeconds": 3600
  }
]

BUCKET_ACCESS_KEY_ID=
BUCKET_SECRET_ACCESS_KEY=
BUCKET_ENDPOINT=
BUCKET_NAME=
BUCKET_REGION=
# if you have a custom domain, you can change the `BUCKET_PUBLIC_URL`
BUCKET_PUBLIC_URL= 

import { S3Client } from '@aws-sdk/client-s3';

const BucketClient = new S3Client({
  region: process.env.BUCKET_REGION,
  endpoint: process.env.BUCKET_ENDPOINT,
  credentials: {
    accessKeyId: process.env.BUCKET_ACCESS_KEY_ID || '',
    secretAccessKey: process.env.BUCKET_SECRET_ACCESS_KEY || '',
  },
});

export default BucketClient;

import "...";

export default async function createPresignedUrl(
  mimeType: string // be like: image/png
): Promise<{ fileUrl: string; presignedUrl: string }> {
  // key be like: 2025/03/01/1234567890.png
  const key = `${createDateFolderPath()}/${nanoid()}.${getFileExtensionByMimeType(
    mimeType
  )}`;

  const command = new PutObjectCommand({
    Bucket: process.env.BUCKET_NAME as string,
    Key: key,
    ContentType: mimeType,
  });

  const presignedUrl = await getSignedUrl(BucketClient, command, {
    expiresIn: 3600,
  });

  const fileUrl = `${process.env.BUCKET_PUBLIC_URL}/${key}`;

  return { fileUrl, presignedUrl };
}

export async function POST(request: NextRequest) {
  // ...
  const results = await Promise.all(
    files.map(async (file) => {
      const { fileUrl, presignedUrl } = await createPresignedUrl(
        file.mimeType
      );
      return {  
        fileUrl, 
        presignedUrl,
      };
    })
  );
  // ...
}

const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();

  const formData = new FormData(e.currentTarget);
  const formFile = formData.get('file') as File;

  // ...
  const res = await fetch('/api/presigned-url', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      files: [
        {
          mimeType: file?.type || '',
          fileSize: file?.size || 0,
        },
      ],
    }),
  });
  // ...
}

<form onSubmit={...}>
  <div className='flex gap-3'>
    <label
      htmlFor='file' // match with <input> id
      className='size-16 flex justify-center items-center rounded-lg bg-sky-500 hover:cursor-pointer'
    >
      <Upload className='size-8' />
      <input
        type='file'
        name='file' // required for form submission
        id='file' // required for <label>
        multiple={false} // (1)true for multiple files (2)false for single file
        onChange={handleFileChange}
        className='hidden'
        accept='image/*' // only allow image files
      />
    </label>
  </div>
</form>

import { getFileNameFromUrl } from '@/lib/file-utils';
import { useCallback, useState } from 'react';

export default function useFileDownload() {
  const [isDownloading, setIsDownloading] = useState(false);

  const fileDownload = useCallback(
    async (url: string) => {
      try {
        setIsDownloading(true);
        // add timestamp to url to avoid browser cache and CORS
        const response = await fetch(`${url}?t=${Date.now()}`); 

        if (!response.ok) {
          throw new Error(`HTTP error! Status: ${response.status}`);
        }

        const blob = await response.blob();
        const link = document.createElement('a');
        link.href = URL.createObjectURL(blob);
        link.download = getFileNameFromUrl(url);
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);

        URL.revokeObjectURL(link.href);
        setIsDownloading(false);
      } catch (error) {
        console.error('download file error:', error);
      } finally {
        setIsDownloading(false);
      }
    },
    [setIsDownloading]
  );

  return { isDownloading, fileDownload };
}

import "...";

/**
 * Creates a presigned URL for a multipart upload.
 *
 * @param {Object} options - The options for creating the presigned URL.
 * @param {string} options.mimeType - The MIME type of the file, e.g., 'image/png'.
 * @param {number} options.fileSize - The size of the file in bytes. (5 Mb ~ 5 Gb)
 * @param {number} [options.partSize=5242880] - The size of each part in bytes. Defaults to 5MB, the minimum part size requirement for R2/S3 Bucket.
 *
 */
export default async function createMultiPartsPresignedUrl({
  mimeType,
  fileSize,
  partSize = 5 * 1024 * 1024,
}: {
  mimeType: string;
  fileSize: number;
  partSize?: number;
}) {
  const bucketName = process.env.BUCKET_NAME || '';
  // key be like: 2025/03/01/1234567890.png
  const key = `${createDateFolderPath()}/${nanoid()}.${getFileExtensionByMimeType(
    mimeType
  )}`;

  // Calculate the part size and count
  const partCount = Math.ceil(fileSize / partSize);

  // Initialize the multipart upload
  const multipartUpload = await BucketClient.send(
    new CreateMultipartUploadCommand({
      Bucket: bucketName,
      Key: key,
      ContentType: mimeType,
    })
  );

  const uploadId = multipartUpload.UploadId; 

  if (!uploadId) {
    throw new Error('Failed to initialize multipart upload');
  }

  // Generate a presigned URL for each part
  const presignedUrlList = [];

  // partNumber start from 1
  // because AWS S3 API PartNumber start from 1, max is 10000
  for (let partNumber = 1; partNumber <= partCount; partNumber++) { 
    const command = new UploadPartCommand({
      Bucket: bucketName,
      Key: key,
      UploadId: uploadId,
      PartNumber: partNumber,
    });

    const presignedUrl = await getSignedUrl(BucketClient, command, {
      expiresIn: 3600,
    });

    presignedUrlList.push({
      presignedUrl,
      partNumber,
    });
  }

  return {
    key,
    uploadId,
    presignedUrlList,
  };
}

{
  key: string;
  uploadId: string;
  parts: {
    partNumber: number;
    etag: string;
  }[];
};

import "...";

export async function POST(request: NextRequest) {
  try {
    // ...

    // Prepare part information for CompleteMultipartUpload, ensuring it's sorted by PartNumber
    const completedParts = parts
      .sort((a, b) => a.partNumber - b.partNumber)
      .map((part) => ({
        PartNumber: part.partNumber,
        ETag: part.etag,
      }));

    const completeCommand = new CompleteMultipartUploadCommand({
      Bucket: process.env.BUCKET_NAME,
      Key: key,
      UploadId: uploadId,
      MultipartUpload: {
        Parts: completedParts,
      },
    });

    try {
      const result = await BucketClient.send(completeCommand);
      console.log('Multipart upload completed successfully:', result);
    } catch (error) {
      console.error('S3 CompleteMultipartUpload error details:', error);
      throw error;
    }

    const fileUrl = `${process.env.BUCKET_PUBLIC_URL}/${key}`;

    // ...
}

'use client';

export default function MultipartsLargeFileUpload() {
  // ...

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    const formData = new FormData(e.currentTarget);
    const formFile = formData.get('file') as File;

    try {
      // (1) create presigned url
      const presignedUrlResponse = await fetch( 
        '/api/multi-parts-presigned-url',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            files: [
              {
                mimeType: file?.type || '',
                fileSize: file?.size || 0,
              },
            ],
          }),
        }
      );

      const presignedUrlJson =
        (await presignedUrlResponse.json()) as MultiPartsPresignedUrlResponse;

      // ...

      const { key, uploadId, presignedUrlList } = presignedUrlJson.data;

      const slicedFileList = sliceFileToMultipart(formFile);

      // (2) upload sliced file
      const uploadResponse = await Promise.all( 
        presignedUrlList.map(async (el, idx) => {
          if (!el.presignedUrl) {
            throw new Error('No presigned url found for upload');
          }

          const sliceResponse = await fetch(el.presignedUrl, {
            method: 'PUT',
            body: slicedFileList[idx],
            headers: {
              'Content-Type': formFile.type,
            },
          });

          if (!sliceResponse.ok) {
            console.error('Upload failed with status:', sliceResponse.status);
            throw new Error(`Upload failed: ${sliceResponse.status}`);
          }

          const etag =
            sliceResponse.headers.get('Etag') ||
            sliceResponse.headers.get('etag') ||
            sliceResponse.headers.get('ETag') ||
            '';

          console.log('Part uploaded with ETag:', etag);

          return {
            etag,
            partNumber: el.partNumber,
          };
        })
      );

      if (!uploadResponse.length) {
        console.log('upload failed');
        return;
      }

      const params: CompletedMultiPartUploadRequestBody = {
        key,
        uploadId,
        parts: uploadResponse.map((el) => ({
          partNumber: el.partNumber,
          etag: el.etag,
        })),
      };

      // (3) tell server all slices is uploaded and get the file url
      const completedRes = await fetch('/api/completed-multi-part-upload', { 
        method: 'POST',
        body: JSON.stringify(params),
      });

      const completedJson = (await completedRes.json()) as {
        fileUrl: string;
      };

      setPreviewUrl(completedJson.fileUrl);
    } catch (error: any) {
      console.log(error);
    } finally {
      setLoading(false);
    }
  };


  return ...
}

export function sliceFileToMultipart(
  file: File,
  sliceSize: number = 5 * 1024 * 1024
): Blob[] {
  const totalSize = file.size;
  const totalSlices = Math.ceil(totalSize / sliceSize);
  const slices = [];

  for (let i = 0; i < totalSlices; i++) {
    const start = i * sliceSize;
    const end = start + sliceSize;
    const slice = file.slice(start, end);
    slices.push(slice);
  }

  return slices;
}