An S3 upload SDK that writes to your own bucket

When a user picks a file, the React component asks your route handler for permission to upload. The handler checks the request against your file router (including the allowed content types), builds an object key from the route name, a random id and a sanitized file name, and signs a presigned PUT URL with the AWS S3 client using your credentials. The browser then sends the file directly to the bucket. The file bytes never pass through your server.

The URL is scoped to one key, one content type and one content length, and the default expiry in the handler code is 900 seconds. After the upload, the component calls the handler again and your onUploadComplete callback runs on your server. If you want the trade-offs of this design in detail, see presigned URLs vs server proxy uploads.

Browser                     Your server                     Your S3 bucket
  |  "Upload imageUploader" --->|                                |
  |                             | signs a presigned URL -------->|
  |  <--- presigned URL --------|                                |
  |  PUT file -----------------------------------------------> |
  |  "Done" ------------------->| runs onUploadComplete          |

Your accessKeyId and secretAccessKey stay in server-side environment variables. Keep the storage config out of client components and out of NEXT_PUBLIC_ variables.

Cloudflare R2

import { createUploadKitHandler } from '@uploadkitdev/next';
import type { FileRouter } from '@uploadkitdev/next';

const router = {
  imageUploader: {
    maxFileSize: '4MB',
    allowedTypes: ['image/*'],
    onUploadComplete: async ({ file }) => {
      console.log('Stored in your R2 bucket:', file.url);
    },
  },
} satisfies FileRouter;

export const { GET, POST } = createUploadKitHandler({
  router,
  storage: {
    endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
    region: 'auto',
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    bucket: process.env.R2_BUCKET_NAME!,
  },
});

R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY_ID=your_r2_access_key_id
R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
R2_BUCKET_NAME=your-bucket-name

AWS S3

import { createUploadKitHandler } from '@uploadkitdev/next';
import type { FileRouter } from '@uploadkitdev/next';

const router = {
  documentUploader: {
    maxFileSize: '16MB',
    allowedTypes: ['application/pdf'],
  },
} satisfies FileRouter;

export const { GET, POST } = createUploadKitHandler({
  router,
  storage: {
    region: process.env.AWS_REGION!,
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    bucket: process.env.AWS_S3_BUCKET!,
  },
});

For S3, the docs recommend an IAM user with s3:PutObject, s3:GetObject, s3:DeleteObject and s3:AbortMultipartUpload on the bucket. Because the browser PUTs to the bucket origin, the bucket also needs a CORS rule that allows your site.

UploadButton, UploadDropzone and useUploadKit work the same whether files go to UploadKit’s managed storage or your bucket. The only difference is that the URLs you get back point at your storage.

<UploadDropzone
  route="imageUploader"
  onUploadComplete={(files) => {
    // files[0].url points to YOUR bucket, not UploadKit's managed storage
    saveToDatabase(files[0].url);
  }}
/>

• Next.js route handler

  createUploadKitHandler from @uploadkitdev/next returns GET and POST for an App Router route.

• Express, Hono, Fastify

  createExpressHandler, createHonoHandler and createFastifyHandler are exported from @uploadkitdev/next/express, /hono and /fastify.

• S3-compatible providers

  The handler uses the AWS S3 client with an optional custom endpoint. The docs show endpoints for R2, AWS S3, MinIO, DigitalOcean Spaces, Wasabi and Backblaze B2.

• Google Cloud Storage factory

  createGCSStorage defaults the endpoint to https://storage.googleapis.com (S3 interoperability). The BYOS docs don’t include a GCS walkthrough, so test it against your own bucket.

import { createHonoHandler } from '@uploadkitdev/next/hono';

app.all('/api/uploadkit/*', createHonoHandler({ router, storage }));

Here storage is the same object you would pass to createUploadKitHandler. See the backend adapters docs for Express and Fastify.

Choose managed if you want no infrastructure to run and the Free or Pro limits fit: Free includes 5 GB of storage and a 4 MB max file, Pro is $15/mo with 100 GB and 512 MB per file. See pricing. Choose BYOS if you need data to stay in a bucket you control, already have storage infrastructure, have compliance requirements, or want your own provider’s rates for high-volume storage. For provider prices, read S3 vs R2 vs Backblaze B2 pricing.

UploadThing stores files on its managed infrastructure (source, checked October 2026). The UploadKit vs UploadThing page covers the comparison.