Full-stack SDK хранения файлов: один API от сервера Next.js до браузера React

Full-stack хранение файлов часто — три разные реализации: серверный upload, клиентская форма и панель с другим API. Files SDK решает это одной API от сервера до браузера.

Если вы выбираете **full-stack SDK хранения файлов** для Next.js или клиентского портала, эта версия заслуживает внимания: gateway, браузерный клиент, адаптеры и опциональный shadcn/ui на одних и тех же глаголах.

Один gateway, много поверхностей

Ядро — **`@files-sdk/api`**. Один endpoint: upload, download, list, search, url, copy, move, delete, capabilities и подписанные URL.

Сервер: **`@files-sdk/next`**, **`@files-sdk/hono`**, Express, Fastify, Koa, Elysia, Nitro, SvelteKit, Astro, Bun, Deno. Клиент: **`createFilesClient`**; **`useFiles`** для React, Vue, Svelte с **`useList`**, **`useFile`**, **`useSearch`**. С **`versioning()`** или **`softDelete()`** — версии, restore, корзина, purge.

Почему раздельные стеки ломаются

Route handler + dropzone хватает до presign, Range, корзины или прав по префиксу. Без **gateway API** каждая фича — новый маршрут, auth расходится.

Auth и транспорт

**Deny-by-default** на операцию: префиксы, сроки, read-only, allowlists origin. Download — redirect или **proxy stream**; proxy с **Range/206** и abort при отключении клиента. Upload **presign → complete** с proxy fallback.

Серверные адаптеры

Для **Files SDK Next.js** — одна смонтированная route с полным набором глаголов. Тот же контракт на Hono, Express и др.—auth один раз, клиент одинаков на Vercel или VPS.

React hooks

**`createFilesClient`** с типами; **`useFiles`** с прогрессом и ошибками. Versioning и soft delete в той же клиентской API—not отдельный admin REST.

Registry shadcn/ui

Компоненты на **`useFiles`**: dropzone, браузер + breadcrumbs, search, preview, share, progress, actions, version history, trash bin.

Когда SDK, а когда свой код

• Browser upload + серверная обработка в одном namespace
• Presign и proxy без двух codebases
• Versioning или trash как продуктовое требование
• Несколько frameworks, одна политика bucket
• shadcn UI без custom file manager

Чеклист

• Смонтировать **`@files-sdk/api`**
• Deny-by-default правила
• Redirect vs proxy downloads
• **`createFilesClient`** + allowlists
• **`useFiles`** в формах и admin
• shadcn: сначала dropzone
• Тест presign на медленных сетях

Для агентств

Клиентские порталы и медиатеки упираются в кастомные права. **Full-stack SDK** объединяет upload, list, search и delete.

Итог

Ставка **one-storage-API**: gateway, адаптеры, **`createFilesClient`**, **`useFiles`**, shadcn—одни глаголы Files. Нужен второй взгляд на архитектуру upload? Напишите.