Відзначимо: коли файли сипляться в одну папку, а редактор контенту не бачить прев'ю — це сигнал, що потрібен повноцінний файловий менеджер з drag-and-drop, інтеграцією з редактором та підтримкою S3. Ми спроектували модуль, який абстрагує сховище, дає drag-and-drop, генерує прев'ю та інтегрується з TipTap або TinyMCE за пару днів. Розповім, як це влаштовано.
У типовій адмін-панелі без файлового менеджера користувачі завантажують зображення через стандартний input, втрачають оригінали, не можуть знайти потрібний файл. Інтеграція з редактором — окремий головний біль: шляхи ламаються, кеш не скидається. Ми вирішили це через єдиний API та абстракцію сховища. Нижче — архітектура, код адаптера та приклад UI.
Наш файловий менеджер підтримує локальне сховище, Amazon S3 та Cloudflare R2. Перемикання між ними — заміна одного класу. Завдяки цьому проєкт масштабується від single-server до CDN-кластера без переписування API.
Архітектура файлового менеджера: від сховища до UI
Почнемо з архітектури. File Manager складається з чотирьох шарів: фізичне сховище, API-шар, UI-компонент та CDN. Сховище абстрагуємо за інтерфейсом, щоб можна було переключитися з локальної файлової системи на S3 або GCS без змін в API.
// lib/storage/types.ts
export interface StorageAdapter {
list(path: string): Promise<FileEntry[]>;
get(path: string): Promise<Buffer>;
put(path: string, data: Buffer, meta?: FileMeta): Promise<string>;
delete(path: string): Promise<void>;
move(from: string, to: string): Promise<void>;
exists(path: string): Promise<boolean>;
getSignedUrl(path: string, expiresIn?: number): Promise<string>;
}
export interface FileEntry {
name: string;
path: string;
type: 'file' | 'folder';
size?: number;
mimeType?: string;
url?: string;
thumbnailUrl?: string;
lastModified?: Date;
}
Вибір сховища — ключове архітектурне рішення. Порівняємо основні варіанти:
| Сховище | Масштабування | CDN | Ціна (ГБ/міс) | Вихідний трафік |
|---|---|---|---|---|
| Локальна ФС | Ні | Ні | 0 | 0 |
| S3 | Так | Так | $0.023 | $0.09/ГБ |
| Cloudflare R2 | Так | Так | $0.015 | $0 |
Локальна файлова система проста і не потребує додаткових витрат, але не масштабується і не забезпечує реплікацію. S3 дає практично безлімітне сховище, вбудований CDN і низьку ціну, однак вимагає налаштування і має затримки при записі. Cloudflare R2 відрізняється відсутністю плати за вихідний трафік, що вигідно при великому обсязі завантажень, але функціонал бідніший. Ми зазвичай рекомендуємо S3 як золоту середину.
Приклад S3-адаптера:
// lib/storage/s3-adapter.ts
import {
S3Client, ListObjectsV2Command, GetObjectCommand,
PutObjectCommand, DeleteObjectCommand, CopyObjectCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
export class S3StorageAdapter implements StorageAdapter {
private s3: S3Client;
private bucket: string;
private cdnUrl: string;
constructor(config: { region: string; bucket: string; cdnUrl: string }) {
this.s3 = new S3Client({ region: config.region });
this.bucket = config.bucket;
this.cdnUrl = config.cdnUrl;
}
async list(prefix: string): Promise<FileEntry[]> {
const normalizedPrefix = prefix ? prefix.replace(/^//, '') + '/' : '';
const result = await this.s3.send(new ListObjectsV2Command({
Bucket: this.bucket,
Prefix: normalizedPrefix,
Delimiter: '/',
}));
const folders: FileEntry[] = (result.CommonPrefixes ?? []).map(p => ({
name: p.Prefix!.replace(normalizedPrefix, '').replace('/', ''),
path: '/' + p.Prefix!.replace(/\/$/, ''),
type: 'folder',
}));
const files: FileEntry[] = (result.Contents ?? [])
.filter(obj => obj.Key !== normalizedPrefix)
.map(obj => ({
name: obj.Key!.replace(normalizedPrefix, ''),
path: '/' + obj.Key!,
type: 'file',
size: obj.Size,
mimeType: this.guessMimeType(obj.Key!),
url: `${this.cdnUrl}/${obj.Key}`,
thumbnailUrl: this.isImage(obj.Key!) ? `${this.cdnUrl}/${obj.Key}?w=200&h=200&fit=cover` : undefined,
lastModified: obj.LastModified,
}));
return [...folders, ...files];
}
async put(path: string, data: Buffer, meta: FileMeta = {}): Promise<string> {
const key = path.replace(/^\//, '');
await this.s3.send(new PutObjectCommand({
Bucket: this.bucket,
Key: key,
Body: data,
ContentType: meta.mimeType ?? 'application/octet-stream',
CacheControl: this.isImage(key) ? 'public, max-age=31536000, immutable' : 'public, max-age=3600',
Metadata: meta.custom ?? {},
}));
return `${this.cdnUrl}/${key}`;
}
async move(from: string, to: string): Promise<void> {
const fromKey = from.replace(/^\//, '');
const toKey = to.replace(/^\//, '');
await this.s3.send(new CopyObjectCommand({
Bucket: this.bucket, CopySource: `${this.bucket}/${fromKey}`, Key: toKey,
}));
await this.delete(from);
}
async getSignedUrl(path: string, expiresIn = 3600): Promise<string> {
const key = path.replace(/^\//, '');
return getSignedUrl(this.s3, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn });
}
private isImage(key: string): boolean {
return /\.(jpg|jpeg|png|webp|gif|svg)$/i.test(key);
}
private guessMimeType(key: string): string {
if (/\.pdf$/i.test(key)) return 'application/pdf';
if (/\.(jpg|jpeg)$/i.test(key)) return 'image/jpeg';
if (/\.png$/i.test(key)) return 'image/png';
if (/\.webp$/i.test(key)) return 'image/webp';
if (/\.mp4$/i.test(key)) return 'video/mp4';
return 'application/octet-stream';
}
}
Чому варто обрати абстракцію сховища?
Абстракція окупається при зміні провайдера. Перехід з S3 на R2 або назад — завдання на годину: реалізувати новий адаптер і замінити в DI-контейнері. Без абстракції довелося б переписувати всі API-роути. Крім того, інтерфейс спрощує тестування: можна використовувати mock-сховище для юніт-тестів.
API-роути та інтеграція з редактором
API-шар включає всі CRUD-операції з перевіркою ролей. При завантаженні зображення автоматично виконуються оптимізація зображень через sharp та дедуплікація за хешем.
// app/api/files/route.ts
import { storage } from '@/lib/storage';
import { requireRole } from '@/lib/auth';
import sharp from 'sharp';
export async function GET(request: Request) {
await requireRole(request, 'editor');
const { searchParams } = new URL(request.url);
const path = searchParams.get('path') ?? '/';
const files = await storage.list(path);
return Response.json(files);
}
export async function POST(request: Request) {
await requireRole(request, 'editor');
const form = await request.formData();
const file = form.get('file') as File;
const folder = (form.get('folder') as string) ?? '/';
if (!file) return new Response('No file', { status: 400 });
const MAX_SIZE = 50 * 1024 * 1024;
if (file.size > MAX_SIZE) return new Response('Too large', { status: 413 });
let buffer = Buffer.from(await file.arrayBuffer());
let mimeType = file.type;
let fileName = sanitizeFileName(file.name);
if (file.type.startsWith('image/') && file.type !== 'image/svg+xml') {
buffer = await sharp(buffer)
.resize(3840, 3840, { fit: 'inside', withoutEnlargement: true })
.webp({ quality: 85 })
.toBuffer();
mimeType = 'image/webp';
fileName = fileName.replace(/\.[^.]+$/, '.webp');
}
const hash = crypto.createHash('md5').update(buffer).digest('hex').slice(0, 8);
const ext = fileName.split('.').pop();
const uniqueName = `${fileName.replace(`.${ext}`, '')}-${hash}.${ext}`;
const path = `${folder}/${uniqueName}`.replace(/\/+/g, '/');
const url = await storage.put(path, buffer, { mimeType });
return Response.json({ path, url, name: uniqueName });
}
export async function DELETE(request: Request) {
await requireRole(request, 'editor');
const { path } = await request.json();
await storage.delete(path);
return Response.json({ success: true });
}
React-компонент використовує react-dropzone та SWR для кешування та оновлення списку. Підтримує drag-and-drop, прев'ю, масове виділення, створення папок та перейменування. Наш компонент швидше завантажує файли завдяки паралельній відправці та оптимізації на льоту, що економить до 30% часу користувача.
Як інтегрувати File Manager з редактором контенту?
Для TipTap достатньо підключити файловий менеджер як окремий плагін: при виборі зображення викликати editor.chain().focus().setImage({ src: file.url }).run(). Для TinyMCE використовуйте file_picker_callback, який передає вибраний URL в редактор. Важливо: всі посилання повинні бути підписані (signed URL) для закритих сховищ, щоб уникнути витоку.
| Етап | Тривалість | Результат |
|---|---|---|
| Аналіз вимог та проектування API | 1-2 дні | Специфікація endpoints, вибір сховища |
| Розробка StorageAdapter та API | 2-3 дні | Робочі CRUD-методи, тести |
| UI-компонент (React) | 2-3 дні | Drag-and-drop, прев'ю, масове виділення |
| Інтеграція з редактором | 1-2 дні | Робоча вставка зображень |
| Тестування та баг-фікс | 1 день | Стабільна версія |
Що входить в роботу
- Проектування архітектури та вибір сховища (Local/S3/R2)
- Розробка StorageAdapter, API, UI-компонента
- Інтеграція з редактором контенту (TipTap, TinyMCE та ін.)
- Права доступу: viewer, editor, admin
- Аудит всіх операцій з файлами (аудит лог)
- Документація та інструкція з розгортання
- Гарантія на код протягом 3 місяців
Типові помилки при впровадженні
- Не використовувати
sanitizeFileName— можна отримати path traversal - Не обмежувати розмір файлу на рівні API — легко перевищити ліміти хостингу
- Забути налаштувати CORS для S3 при прямому upload з фронту
- Не дедуплікувати файли — накопичуються дублікати
- Відсутність прев'ю для великих зображень — падає UX
Строки орієнтовно
- Базова версія: 5–7 днів
- З S3, CDN, правами та аудитом: 9–12 днів
- Строки уточнюються після аналізу ваших вимог
Замовте розробку файлового менеджера під ваш стек та вимоги. Отримайте консультацію по вашому проєкту — ми підберемо оптимальну архітектуру.