Skip to content

File uploads

form() reads multipart/form-data bodies; files are File objects, Bun’s, with name, type, size and the content.

One file

const Avatar = z.object({
avatar: z
.instanceof(File)
.refine((file) => ['image/png', 'image/jpeg', 'image/webp'].includes(file.type), 'PNG, JPEG or WebP is expected'),
})
type Avatar = z.infer<typeof Avatar>
@Post('me/avatar', [form(Avatar, { maxFileSize: 2 * 1024 * 1024, maxFiles: 1 }), value(USER)])
@HttpCode(204)
async uploadAvatar(input: Avatar, user: User) {
await Bun.write(`uploads/${user.id}.img`, input.avatar)
}
Terminal window
curl -X POST localhost:3000/me/avatar -F avatar=@photo.png -H "authorization: Bearer $TOKEN"

Several files and fields

A repeated field, or a field named photos[], is an array:

const Album = z.object({
title: z.string().min(1),
photos: z.array(z.instanceof(File)).min(1).max(20),
})
type Album = z.infer<typeof Album>
@Post('albums', [form(Album, { maxFileSize: 10 * 1024 * 1024, maxFiles: 20, maxBodySize: 100 * 1024 * 1024 })])
create(album: Album) {}

A single photos field gives a single File, not an array: z.array() then refuses it. Name the field photos[] in the client to always get an array.

Limits

Each limit answers 413 as soon as it is exceeded:

Limit
maxBodySize bytes of the whole body, checked while it is read: a huge upload is refused without being stored
maxFileSize bytes of each file
maxFiles number of files
maxFields number of fields, files included

Without maxBodySize, the server’s maxRequestBodySize (Bun’s 128 MiB unless lowered in listen()) still applies. Set limits on every upload route: a form without them accepts as many files as the client sends.

Content type

file.type is what the client declared. When it matters, check the content itself, its first bytes for instance:

const isPng = async (file: File) => {
const head = new Uint8Array(await file.slice(0, 8).arrayBuffer())
return [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((byte, i) => head[i] === byte)
}

Never build a path from file.name: it is written by the client, ../../etc/passwd included. Name stored files yourself, with an id.

Storage

Bun.write(path, file) stores on disk. For S3 and compatible storages (R2, MinIO), Bun has a client built in:

import { s3 } from 'bun'
await s3.write(`avatars/${user.id}`, input.avatar, { type: input.avatar.type })

It reads its credentials from S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET and S3_ENDPOINT.

Downloads

Return a file, or Bun.file(), and it is streamed:

@Get('files/:id', [param('id', uuid)])
download(id: string) {
return new Response(Bun.file(`uploads/${id}`), {
headers: { 'content-disposition': `attachment; filename="${id}"` },
})
}