Adding an Upload Kind

Declare an image an owner has as data: the owner, the table and column that hold its URL, an organization kind's permission, and its limits.

A kind is data in apps/web/config/storage.config.server.ts (the kit's own user-avatar is in storage-kit-kinds.server.ts; a kind of yours can't replace it): who owns the image, and the column on the owner's row that holds its URL. Storage writes that column; never write it yourself.

// apps/web/config/storage.config.server.ts
import { RENAME_ORGANIZATION } from '@kit/organizations';
import { defineUploadKinds } from '@kit/storage/server';
import { organization } from '#/db/schema.ts';
export const uploadKinds = defineUploadKinds({
// the active organization's logo, for members allowed to rename it
'org-logo': {
owner: 'organization',
table: organization,
column: organization.logo,
permission: RENAME_ORGANIZATION,
maxDimension: 256,
},
});

That's all: POST /api/uploads/org-logo now works for an owner or admin of the active organization, GET /api/files/org-logo/… serves the result, deleting the organization purges its logos, and the weekly sweep covers the kind.

Upload and remove from the browser with @kit/storage/client, which uses Uppy (@uppy/core, @uppy/xhr-upload, @uppy/compressor, loaded on first use, never in the initial bundle):

import { removeImage, uploadImage } from '@kit/storage/client';
const result = await uploadImage({
kind: 'user-avatar',
file,
onProgress: (percent) => setProgress(percent),
});
if (result.ok) {
result.url; // also now in user.image
} else {
t(`storage.errors.${result.errorKey}`); // kit messages, one per server answer
}
await removeImage({ kind: 'user-avatar' }); // { ok: true } on the route's 204

What the client does, all UX only (the server still checks everything):

  • Shrinks an image that is over 2 MB or over the server's pixel budget (2048 px a side) in the browser first, so a 12 MP phone photo fits both limits; that re-encode also applies the EXIF rotation. A PNG over 2 MB becomes a JPEG, which loses its transparency. A file that already fits goes up untouched, so the server alone judges it (an animated image is refused there).
  • Refuses a file that is not PNG, JPEG or WebP, or that is still over 2 MB after shrinking, before any request.
  • Sends one multipart file field to /api/uploads/<kind> and nothing else: no owner id, and a neutral file name. Never retries a send.
  • Maps every answer to a key under storage.errors (unsupportedType, animated, tooLargeDimensions, invalidImage, tooLarge, tooManyUploads, unauthenticated, forbidden, notFound, conflict, unavailable, failed); an unknown one is failed. uploadErrorKey maps a status and code yourself.

Without the client, a plain same-origin multipart POST (fetch('/api/uploads/<kind>', { method: 'POST', body }) with a file field) works the same way.

The Fields

Field
owner'user' or 'organization'Whose image it is: the session's user, or its verified active organization
table, columnDrizzle table and a text column on itThe owner row (with an id column) and the column holding the URL
permissionRequired for 'organization'Checked with hasPermission on the caller's membership; no active organization is a 403
maxBytes1 to 2 MB (default 2 MB)Largest file accepted
maxDimension1 to 2048 px (default 512)Longest side after the resize

The name is lowercase letters, digits and -. A bad name, a limit past its cap, or a column not on its table stops the app at load, not on the first upload.

Rules

  • A user kind is only ever the caller's own image. There is no way to upload for another user; don't build one.
  • An organization kind always names a permission. Reuse one from @kit/organizations or your roles; every member who has it can replace the image.
  • Public images only. See Images Are Public.
  • Never write the column yourself, from a page action, Better Auth or SQL: storage compares it to decide what to delete. Removing goes through DELETE /api/uploads/<kind>.
  • A column may hold a URL storage didn't write (an OAuth avatar in user.image): storage replaces or clears it but never deletes anything for it.

Renaming or Removing a Kind

Its stored files keep their old prefix and stop being served. Before removing a kind, clear the column for its owners (or keep the kind until you have); objects under a prefix no kind uses are left in R2.