# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/storage/upload-kinds*

---

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

```ts
// 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](https://uppy.io) (`@uppy/core`, `@uppy/xhr-upload`, `@uppy/compressor`, loaded on first use, never in the initial bundle):

```ts
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`, `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/organizations` or your roles; every member who has it can replace the image.
- **Public images only.** See [Images Are Public](./overview#images-are-public-to-anyone-with-the-url).
- **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.
