Image Transformations (/docs/compute/image-transformations)

For the complete Prisma documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL.

Resize, encode, cache, and serve images from a Prisma Compute app using Bun's native image pipeline and ordinary HTTP routes.

Location: Compute > Image Transformations

Prisma Compute apps run on Bun, and Bun ships Bun.Image: a native pipeline for decoding, resizing, rotating, flipping, adjusting, and re-encoding images. So you build image transformations as part of your app, not as a separate image service.

A transformation route is an ordinary Compute deployment. It receives a request, uses CPU and memory, and returns bytes. It is billed and operated like every other route in your app.

Bun.Image supports the common image optimization path:

Stick to JPEG, PNG, and WebP for portable Compute routes. Bun's HEIC and AVIF support depends on operating-system image backends, so treat those formats as unavailable unless you add and test your own encoder path.

Build the route in a Hono or plain Bun HTTP app. The example below uses Hono to match the other Compute examples; the Bun.Image code is identical in any framework.

bun add hono

import { Hono } from "hono";

const app = new Hono();

const IMAGE_ORIGIN = "https://assets.example.com/";
const MAX_DIMENSION = 2400;
const MAX_PIXELS = 4096 * 4096;

function parseDimension(value: string | undefined) {
  if (!value) return undefined;
  const parsed = Number.parseInt(value, 10);
  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
  return Math.min(parsed, MAX_DIMENSION);
}

function parseQuality(value: string | undefined) {
  if (!value) return 80;
  const parsed = Number.parseInt(value, 10);
  if (!Number.isFinite(parsed)) return 80;
  return Math.min(Math.max(parsed, 1), 100);
}

function negotiateFormat(request: Request, requested: string | undefined) {
  if (requested === "jpeg" || requested === "png" || requested === "webp") {
    return requested;
  }

  const accept = request.headers.get("accept") ?? "";
  return accept.includes("image/webp") ? "webp" : "jpeg";
}

async function applyResize(image: Bun.Image, width?: number, height?: number, fit: "fill" | "inside" = "inside") {
  const options = {
    fit,
    withoutEnlargement: true,
    filter: "lanczos3" as const,
  };

  if (width && height) return image.resize(width, height, options);
  if (width) return image.resize(width, undefined, options);

  if (height) {
    const metadata = await image.metadata();
    const computedWidth = Math.max(1, Math.round((metadata.width * height) / metadata.height));
    return image.resize(computedWidth, height, options);
  }

  return image;
}

function assertImagePath(path: string) {
  if (!/^[a-zA-Z0-9/_ .-]+\.(jpe?g|png|webp)$/i.test(path)) {
    throw new Error("Invalid image path");
  }
}

app.get("/images/*", async (c) => {
  const path = c.req.path.replace(/^\/images\//, "");

  try {
    assertImagePath(path);
  } catch {
    return c.text("Invalid image path", 400);
  }

  const sourceUrl = new URL(path, IMAGE_ORIGIN);
  const source = await fetch(sourceUrl);

  if (!source.ok) {
    return c.text("Source image not found", 404);
  }

  const input = await source.arrayBuffer();
  const width = parseDimension(c.req.query("w"));
  const height = parseDimension(c.req.query("h"));
  const quality = parseQuality(c.req.query("q"));
  const fit = c.req.query("fit") === "fill" ? "fill" : "inside";
  const format = negotiateFormat(c.req.raw, c.req.query("format"));

  let image = new Bun.Image(input, {
    maxPixels: MAX_PIXELS,
    autoOrient: true,
  });

  image = await applyResize(image, width, height, fit);

  if (format === "webp") {
    image = image.webp({ quality });
  } else if (format === "png") {
    image = image.png({ compressionLevel: 6 });
  } else {
    image = image.jpeg({ quality, progressive: true });
  }

  const body = await image.blob();

  return new Response(body, {
    headers: {
      "Cache-Control": "public, max-age=31536000, immutable",
      "Content-Type": body.type,
      "Vary": "Accept",
    },
  });
});

export default app;

Deploy it by pushing once you have set up deploy on push, or follow Deploy your first app to set the project up first.

Request variants:

/images/products/chair.jpg?w=640&q=75
/images/products/chair.jpg?w=1280&format=webp
/images/products/chair.jpg?w=512&h=512&fit=inside

This example sends Cache-Control: immutable, which is only safe when the source path is versioned (a content hash or version segment). If chair.jpg can change in place, drop immutable and use a shorter max-age with an ETag. See Caching for the full rules.

Bun.Image accepts a path, bytes, or a Blob. On Compute, prefer bytes or trusted storage handles over raw user-controlled paths.

const response = await fetch(sourceUrl);
if (!response.ok) throw new Error("Image not found");

const image = new Bun.Image(await response.arrayBuffer(), {
  maxPixels: 4096 * 4096,
  autoOrient: true,
});

Validate remote sources before fetching them:

• Allow only trusted hostnames or storage prefixes.
• Reject private network addresses if users can submit URLs.
• Cap redirects or disable them when you do not need them.
• Set a maximum decoded pixel count with maxPixels.
• Cap requested dimensions and quality.

const image = Bun.file("public/avatars/alice.png").image();

Do not pass a user-controlled string directly to new Bun.Image(path). If the source is user-selected, resolve it through your own database or object store first, then read the trusted object.

An Object Store bucket in the same project works here directly: set its credentials as the S3_* environment variables and Bun.s3 reads them.

const image = Bun.s3("uploads/photo.jpg").image();

You can also write generated variants back to S3:

await Bun.s3("uploads/photo.jpg")
  .image()
  .resize(640, undefined, { withoutEnlargement: true })
  .webp({ quality: 80 })
  .write(Bun.s3("variants/photo-640.webp"));

image.resize(800);
image.resize(800, 600);
image.resize(800, 600, { fit: "inside" });
image.resize(800, 600, { withoutEnlargement: true });
image.resize(800, 600, { filter: "mitchell" });

Use fit: "inside" for the common thumbnail behavior: preserve aspect ratio and fit within a box. Without fit: "inside", width and height produce an exact output size, which can stretch the image.

Use withoutEnlargement: true when handling user uploads or product assets so small source images are not upscaled.

image.rotate(90);
image.flip();
image.flop();

rotate() accepts multiples of 90 degrees.

image.modulate({
  brightness: 1.1,
  saturation: 0,
});

saturation: 0 creates a grayscale output.

image.jpeg({ quality: 82, progressive: true });
image.png({ compressionLevel: 6 });
image.png({ palette: true, colors: 64, dither: true });
image.webp({ quality: 80 });
image.webp({ lossless: true });

If you do not choose an output format, Bun reuses the source format.

const placeholder = await Bun.file("hero.jpg").image().placeholder();

Inline the result as a low-quality placeholder in HTML or React components while the full image loads.

To implement format=auto, inspect the Accept header.

function autoFormat(request: Request) {
  const accept = request.headers.get("accept") ?? "";
  if (accept.includes("image/webp")) return "webp";
  return "jpeg";
}

Return Vary: Accept when the same URL can produce different formats:

return new Response(body, {
  headers: {
    "Content-Type": body.type,
    "Vary": "Accept",
  },
});

Every unique URL should map to one deterministic output. Keep query parameters normalized and bounded.

Recommended cache rules:

• Include all transformation parameters in the URL or path.
• Sort query parameters when generating URLs from code.
• Use immutable cache headers for versioned source paths.
• Use shorter cache headers or ETags when the source can change in place.
• Return Vary: Accept when format negotiation depends on request headers.
• Add a source version, hash, or updated timestamp to the URL when invalidating.

Example:

headers.set("Cache-Control", "public, max-age=31536000, immutable");
headers.set("Vary", "Accept");

Vercel Image Optimization supports framework image components, width and quality parameters, automatic format selection, source allowlists, caching, and fixed source limits. On Prisma Compute, implement those pieces in the app route.

Cloudflare Images exposes many URL and Worker options. The table below maps each option to the Compute implementation path.

If you need operations that Bun.Image does not expose, add a library and keep the same route shape:

1. Validate source, dimensions, format, and quality.
2. Fetch or read the trusted source.
3. Run native Bun transformations for the common path when possible.
4. Route advanced presets through the library.
5. Return the same cache headers and error behavior.

Keep advanced transformations behind named presets instead of exposing every option directly. For example:

/images/products/chair.jpg?p=thumb
/images/products/chair.jpg?p=hero
/images/products/chair.jpg?p=square

Presets make cache keys stable and prevent users from creating unbounded transformation combinations.

• Do not pass user-controlled filesystem paths to new Bun.Image(path).
• Allowlist remote origins before fetching.
• Reject private IP ranges for user-submitted URLs.
• Cap width, height, quality, DPR, and decoded pixels.
• Prefer named presets for public image URLs.
• Return clear 400 responses for invalid parameters.
• Return 404 for missing source images.
• Set Vary: Accept when negotiating formats.
• Use maxPixels to reject decompression bombs before pixel allocation.
• Do not use reversible transformations such as blur as an access-control mechanism.

• Deploy your first app: take a route like this one to a live URL.
• Deployments: build, deploy, logs, promote, and roll back.
• Environment variables: point a preview at a staging bucket and production at a production one.
• Branching: give every image route its own isolated preview.
• Pricing: how request, CPU, memory, and bandwidth metering works.

• Alchemy: Provision Prisma Postgres and deploy applications to Prisma Compute in one TypeScript stack.
• Branching: Branches are isolated environments that map to your Git branches, so preview work never touches production.
• Deploy Button: Add a Deploy with Prisma button that copies a public Composer repository and starts a Composer-managed deployment.
• Deploy on push: Graduate a Composer app from manual deploys to a Git workflow, with production deploys on push and an isolated preview environment per branch.
• Deployments: How deploys create service versions on Prisma Compute, and how to inspect, promote, roll back, start, and stop them.