When files pile into a single folder and the content editor can't see image previews, you need a full-featured file manager with drag-and-drop file upload and S3 integration for your admin panel. Our file manager simplifies file management tasks, abstracts storage, and integrates with TipTap or TinyMCE in a couple of days. Here's how it's built.
In a typical admin panel without a file manager, users upload images via a standard input, lose originals, and can't locate files easily. Integration with the editor is a separate headache: paths break, cache doesn't clear. We solved this through a unified API and storage abstraction. Below are the architecture, adapter code, and example UI.
Our file manager supports local storage, Amazon S3, and Cloudflare R2. Switching between them is a matter of replacing one class. This allows the project to scale from a single server to a CDN cluster without rewriting the API.
What Are the Benefits of Storage Abstraction?
Let's start with the architecture. The file manager consists of four layers: physical storage, API layer, UI component, and CDN. We abstract storage behind an interface so you can switch from a local filesystem to S3 or GCS without changes to the 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;
}
Choosing the right storage is a key architectural decision. Here's a comparison of the main options:
| Storage | Scalability | CDN | Price (GB/month) | Outbound traffic |
|---|---|---|---|---|
| Local FS | No | No | 0 | 0 |
| S3 | Yes | Yes | $0.023 | $0.09/GB |
| Cloudflare R2 | Yes | Yes | $0.015 | $0 |
For most projects, S3 provides the best balance of scalability and cost, offering virtually unlimited storage at $0.023/GB, which is 33% cheaper than typical alternatives for outbound traffic.
Local filesystem is simple and requires no additional cost, but it doesn't scale or provide replication. S3 offers virtually unlimited storage, built-in CDN, and low price, but requires setup and has write latency. Cloudflare R2 has no outbound traffic fees, which is beneficial for large downloads, but its feature set is more limited. We usually recommend S3 as the sweet spot.
Example S3 adapter:
// 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';
}
}
How to Implement API Routes and Editor Integration?
The API layer includes all CRUD operations with role checks. On image upload, automatic image optimization via sharp and deduplication by hash are applied.
// 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 });
}
The React component uses react-dropzone and SWR for caching and list updates. It supports drag-and-drop, preview, bulk selection, folder creation, and renaming. Our component loads files faster by parallel uploads and on-the-fly optimization, saving up to 30% of user time.
Integrating the File Manager with a Content Editor
For TipTap, simply connect the file manager as a separate plugin: on image selection, call editor.chain().focus().setImage({ src: file.url }).run(). For TinyMCE, use the file_picker_callback, which passes the selected URL to the editor. Important: all links should be signed (signed URL) for private storage to prevent leaks.
Implementation Steps
- Choose a storage adapter (local FS, S3, or R2).
- Implement the StorageAdapter interface with CRUD methods.
- Build API endpoints for file operations.
- Develop the React UI with drag-and-drop, preview, and bulk selection.
- Integrate with your content editor (TipTap or TinyMCE).
- Add role-based access control and audit logging.
| Stage | Duration | Result |
|---|---|---|
| Requirements analysis and API design | 1-2 days | Endpoint specification, storage choice |
| StorageAdapter and API development | 2-3 days | Working CRUD methods, tests |
| UI component (React) | 2-3 days | Drag-and-drop, preview, bulk selection |
| Editor integration | 1-2 days | Working image insertion |
| Testing and bug fixes | 1 day | Stable version |
What's Included
- Architecture design and storage selection (Local/S3/R2)
- StorageAdapter, API, and UI component development
- Content editor integration (TipTap, TinyMCE, etc.)
- Access rights: viewer, editor, admin
- Audit logging for all file operations
- Documentation and deployment instructions
- Code warranty for 3 months
Common Mistakes When Implementing
- Not using
sanitizeFileName— can lead to path traversal - Not limiting file size at the API level — easily exceeding hosting limits
- Forgetting to configure CORS for S3 when uploading directly from the frontend
- Not deduplicating files — accumulates duplicates
- Missing previews for large images — degrades UX
Estimated Timelines
- Basic version: 5–7 days
- With S3, CDN, access rights, and audit: 9–12 days
- Timelines are refined after analyzing your requirements
Request file manager development tailored to your stack and needs. Get a consultation for your project — we'll choose the optimal architecture.