feat: implement zero-config local filesystem storage driver for out-of-the-box file uploads on Hugging Face Spaces

src/app/api/storage/actions.ts

@@ -11,7 +11,7 @@ export async function getStorageInfoAction() {
   return {
     type: storageDriver,
     supportsDirectUpload:
-      storageDriver === "vercel-blob" || storageDriver === "s3",
+      storageDriver === "vercel-blob" || storageDriver === "s3" || storageDriver === "local",
   };
 }
 
@@ -69,20 +69,24 @@ export async function checkStorageAction(): Promise<StorageCheckResult> {
       };
     }
 
-    // Warn if neither a public base URL nor a public bucket policy is set.
-    // We can't reliably detect bucket policy here; we just pass validation.
     return { isValid: true };
   }
 
-  // 3. Validate storage driver
-  if (!["vercel-blob", "s3"].includes(storageDriver)) {
+  // 3. Local filesystem storage
+  if (storageDriver === "local") {
+    return { isValid: true };
+  }
+
+  // 4. Validate storage driver
+  if (!["vercel-blob", "s3", "local"].includes(storageDriver)) {
     return {
       isValid: false,
       error: `Invalid storage driver: ${storageDriver}`,
       solution:
         "FILE_STORAGE_TYPE must be one of:\n" +
         "- 'vercel-blob' (default)\n" +
-        "- 's3' (coming soon)",
+        "- 's3'\n" +
+        "- 'local'",
     };
   }
 

src/app/api/storage/file/[key]/route.ts

@@ -0,0 +1,41 @@
+import { NextRequest, NextResponse } from "next/server";
+import fs from "fs/promises";
+import path from "path";
+
+const UPLOADS_DIR = "/tmp/uploads";
+
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ key: string }> },
+) {
+  const { key } = await params;
+  const filePath = path.join(UPLOADS_DIR, key);
+
+  try {
+    const fileBuffer = await fs.readFile(filePath);
+    
+    // Parse original filename from key (Format: timestamp-random-filename)
+    const filename = key.split("-").slice(2).join("-") || "file";
+    const ext = path.extname(filename).toLowerCase();
+    
+    let contentType = "application/octet-stream";
+    if (ext === ".png") contentType = "image/png";
+    else if (ext === ".jpg" || ext === ".jpeg") contentType = "image/jpeg";
+    else if (ext === ".gif") contentType = "image/gif";
+    else if (ext === ".svg") contentType = "image/svg+xml";
+    else if (ext === ".pdf") contentType = "application/pdf";
+    else if (ext === ".txt") contentType = "text/plain";
+    else if (ext === ".json") contentType = "application/json";
+    else if (ext === ".csv") contentType = "text/csv";
+
+    return new NextResponse(fileBuffer, {
+      headers: {
+        "Content-Type": contentType,
+        "Content-Disposition": `inline; filename="${encodeURIComponent(filename)}"`,
+        "Cache-Control": "public, max-age=31536000, immutable",
+      },
+    });
+  } catch (error) {
+    return new NextResponse("File not found", { status: 404 });
+  }
+}

src/lib/file-storage/index.ts

@@ -3,20 +3,21 @@ import { IS_DEV } from "lib/const";
 import type { FileStorage } from "./file-storage.interface";
 import { createS3FileStorage } from "./s3-file-storage";
 import { createVercelBlobStorage } from "./vercel-blob-storage";
+import { createLocalFileStorage } from "./local-file-storage";
 import logger from "logger";
 
-export type FileStorageDriver = "vercel-blob" | "s3";
+export type FileStorageDriver = "vercel-blob" | "s3" | "local";
 
 const resolveDriver = (): FileStorageDriver => {
   const candidate = process.env.FILE_STORAGE_TYPE;
 
   const normalized = candidate?.trim().toLowerCase();
-  if (normalized === "vercel-blob" || normalized === "s3") {
+  if (normalized === "vercel-blob" || normalized === "s3" || normalized === "local") {
     return normalized;
   }
 
-  // Default to Vercel Blob
-  return "vercel-blob";
+  // If no env is configured, default to local filesystem storage
+  return "local";
 };
 
 declare global {
@@ -33,6 +34,8 @@ const createFileStorage = (): FileStorage => {
       return createVercelBlobStorage();
     case "s3":
       return createS3FileStorage();
+    case "local":
+      return createLocalFileStorage();
     default: {
       const exhaustiveCheck: never = storageDriver;
       throw new Error(`Unsupported file storage driver: ${exhaustiveCheck}`);

src/lib/file-storage/local-file-storage.ts

@@ -0,0 +1,96 @@
+import { FileStorage, UploadContent, UploadOptions, UploadResult, FileMetadata } from "./file-storage.interface";
+import fs from "fs/promises";
+import path from "path";
+import { BASE_URL } from "lib/const";
+
+const UPLOADS_DIR = "/tmp/uploads";
+
+export class LocalFileStorage implements FileStorage {
+  constructor() {
+    fs.mkdir(UPLOADS_DIR, { recursive: true }).catch(() => {});
+  }
+
+  async upload(content: UploadContent, options?: UploadOptions): Promise<UploadResult> {
+    const filename = options?.filename || "file";
+    const contentType = options?.contentType || "application/octet-stream";
+    const key = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}-${filename}`;
+    const filePath = path.join(UPLOADS_DIR, key);
+
+    let buffer: Buffer;
+    if (Buffer.isBuffer(content)) {
+      buffer = content;
+    } else if (content instanceof ArrayBuffer) {
+      buffer = Buffer.from(content);
+    } else if (ArrayBuffer.isView(content)) {
+      buffer = Buffer.from(content.buffer, content.byteOffset, content.byteLength);
+    } else if (content instanceof Blob) {
+      buffer = Buffer.from(await content.arrayBuffer());
+    } else if (typeof (content as any).read === "function" || typeof (content as any).on === "function") {
+      const chunks: any[] = [];
+      for await (const chunk of content as any) {
+        chunks.push(chunk);
+      }
+      buffer = Buffer.concat(chunks);
+    } else {
+      throw new Error("Unsupported upload content type");
+    }
+
+    await fs.writeFile(filePath, buffer);
+
+    const metadata: FileMetadata = {
+      key,
+      filename,
+      contentType,
+      size: buffer.length,
+      uploadedAt: new Date(),
+    };
+
+    return {
+      key,
+      sourceUrl: `${BASE_URL}/api/storage/file/${key}`,
+      metadata,
+    };
+  }
+
+  async download(key: string): Promise<Buffer> {
+    const filePath = path.join(UPLOADS_DIR, key);
+    return fs.readFile(filePath);
+  }
+
+  async delete(key: string): Promise<void> {
+    const filePath = path.join(UPLOADS_DIR, key);
+    await fs.unlink(filePath).catch(() => {});
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const filePath = path.join(UPLOADS_DIR, key);
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async getMetadata(key: string): Promise<FileMetadata | null> {
+    const filePath = path.join(UPLOADS_DIR, key);
+    try {
+      const stat = await fs.stat(filePath);
+      return {
+        key,
+        filename: key.split("-").slice(2).join("-") || "file",
+        contentType: "application/octet-stream",
+        size: stat.size,
+        uploadedAt: stat.mtime,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async getSourceUrl(key: string): Promise<string | null> {
+    return `${BASE_URL}/api/storage/file/${key}`;
+  }
+}
+
+export const createLocalFileStorage = () => new LocalFileStorage();