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.
Recipe: An Organization Logo
// apps/web/config/storage.config.server.tsimport { 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 204What 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
filefield 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 isfailed.uploadErrorKeymaps a status andcodeyourself.
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, column | Drizzle table and a text column on it | The owner row (with an id column) and the column holding the URL |
permission | Required for 'organization' | Checked with hasPermission on the caller's membership; no active organization is a 403 |
maxBytes | 1 to 2 MB (default 2 MB) | Largest file accepted |
maxDimension | 1 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/organizationsor 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.