Bun.js + S3 + Sharp: an image upload and optimization pipeline

Architecture without proxying file bytes

Bun is the control plane; object storage is the data plane.

Prepare upload

The client sends filename, MIME type, and size. The API checks the allowlist and returns a key plus presigned URL.

Upload directly

The browser performs PUT to S3. Your Bun process does not hold the file in memory.

Process

A worker reads the original and Sharp creates a thumbnail and WebP preview.

Publish

Store only verified keys, dimensions, MIME type, and processing status in the database.

The file goes directly to storage, so Bun handles access control and metadata instead of proxying large bytes.

Step 1: install the SDK and Sharp

Add dependencies

BASH

bun add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner sharp

Sharp has native components; verify optional dependencies for the target Docker platform.

Set the bucket

ENV

S3_REGION=eu-central-1
S3_BUCKET=media
S3_ENDPOINT=https://s3.example.com
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

S3_ENDPOINT also supports R2 and MinIO. Never expose the secret key to the frontend.

Step 2: issue a presigned PUT URL

Keep the URL short-lived, use a random object key, and bind it to the expected Content-Type. Verify the actual object size after upload.

import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
const s3 = new S3Client({ region: Bun.env.S3_REGION!, endpoint: Bun.env.S3_ENDPOINT || undefined, forcePathStyle: Boolean(Bun.env.S3_ENDPOINT) });
const allowed = new Set(["image/jpeg", "image/png", "image/webp"]);
export async function createUploadUrl(contentType: string) {
  if (!allowed.has(contentType)) throw new Error("Unsupported image type");
  const key = `originals/${crypto.randomUUID()}`;
  const command = new PutObjectCommand({ Bucket: Bun.env.S3_BUCKET!, Key: key, ContentType: contentType, ServerSideEncryption: "AES256" });
  return { key, url: await getSignedUrl(s3, command, { expiresIn: 300 }) };
}

Step 3: create variants with Sharp

Do not trust the file extension. Decode the file server-side and reject invalid or oversized images before publishing.

import sharp from "sharp";
export async function makeVariants(input: Buffer) {
  const image = sharp(input, { limitInputPixels: 40_000_000 });
  const metadata = await image.metadata();
  if (!metadata.width || !metadata.height) throw new Error("Invalid image");
  const thumbnail = await image.clone().rotate().resize({ width: 480, height: 480, fit: "cover" }).webp({ quality: 78 }).toBuffer();
  const preview = await image.clone().rotate().resize({ width: 1600, withoutEnlargement: true }).webp({ quality: 84 }).toBuffer();
  return { thumbnail, preview, width: metadata.width, height: metadata.height };
}

rotate() handles EXIF orientation; withoutEnlargement avoids inflating small images.

Prepare uploads and track processing

Do not mark a file ready when the URL is issued. Create a pending record, then let a callback or worker move it to ready after verifying the object.

import { Elysia, t } from "elysia";
import { createUploadUrl } from "../storage";
export const uploadRoutes = new Elysia({ prefix: "/uploads" }).post("/prepare", async ({ body, set }) => {
  const upload = await createUploadUrl(body.contentType);
  // Persist upload.key and userId with status=pending.
  set.status = 201;
  return { ...upload, status: "pending" };
}, { body: t.Object({ contentType: t.Union([t.Literal("image/jpeg"), t.Literal("image/png"), t.Literal("image/webp")]) }) });

The worker should verify object metadata again before calling Sharp.

Security and cost controls

Upload endpoints need limits at every stage.

Limit size

Limit API payloads and verify the actual object size after PUT.

Generate keys server-side

Use UUIDs and a user/project namespace instead of accepting arbitrary keys.

Scan or moderate

For public content, add antivirus or moderation before status becomes ready.

Add lifecycle rules

Automatically delete abandoned uploads and temporary originals.

Move heavy work to a worker

Keep the request API responsive by separating Sharp processing.

Test the image pipeline

Test decoded output, not just an HTTP status. This catches quality regressions and broken native dependencies after a Docker update.

import { expect, test } from "bun:test";
import sharp from "sharp";
import { makeVariants } from "./images";
test("creates a bounded WebP thumbnail", async () => {
  const input = await sharp({ create: { width: 1200, height: 800, channels: 3, background: "#f97316" } }).png().toBuffer();
  const { thumbnail } = await makeVariants(input);
  const meta = await sharp(thumbnail).metadata();
  expect(meta.format).toBe("webp"); expect(meta.width).toBe(480); expect(meta.height).toBe(480);
});

Run bun test --coverage; use MinIO or a dedicated test bucket for storage integration tests.

FAQ

Does Sharp work on Bun?

Yes, but Sharp has native dependencies. Install them for the target OS and architecture and run a production Docker smoke test.

Should files pass through Bun?

For large files, no. Issue a presigned URL and upload directly to S3-compatible storage; Bun should manage permissions, metadata, and processing state.

Reviewed: 27 Aug 2026Applies to: Bun 1.3+Applies to: AWS SDK v3Applies to: Sharp 0.34+Applies to: Amazon S3 or S3-compatible storageTested with: Bun runtimeTested with: @aws-sdk/client-s3Tested with: @aws-sdk/s3-request-presignerTested with: Sharp

Conclusion

Describe the task — first 15 minutes of consultation are free.