File uploads with a Route Handler in the App Router

A file upload in the App Router goes through a POST Route Handler that reads await request.formData(), checks type and size, and writes to storage. The 1 MB default cap on a Server Action is not a preference: it is a limit.

Why not a Server Action

A Server Action lets you raise bodySizeLimit, but the payload still crosses React's serialisation layer. For large files a Route Handler gives streaming, explicit HTTP statuses and no serialisation in between.

// app/api/upload/route.ts
import { NextResponse } from "next/server";
import { writeFile, mkdir } from "node:fs/promises";
import path from "node:path";

export const runtime = "nodejs";

export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get("file");
  if (!(file instanceof File)) {
    return NextResponse.json({ error: "missing file" }, { status: 400 });
  }
  if (file.size > 5 * 1024 * 1024) {
    return NextResponse.json({ error: "too large" }, { status: 413 });
  }
  const bytes = Buffer.from(await file.arrayBuffer());
  const name = crypto.randomUUID() + "-" + path.basename(file.name);
  await mkdir(path.join(process.cwd(), "uploads"), { recursive: true });
  await writeFile(path.join(process.cwd(), "uploads", name), bytes);
  return NextResponse.json({ name }, { status: 201 });
}

What to check, really

A serverless function's filesystem is read-only except /tmp, and /tmp disappears when the instance restarts. In production write to object storage and return a signed URL, not a local path.

Verify with curl

curl -i -X POST http://localhost:3000/api/upload -F "file=@./prova.png"
# 201 con { "name": "..." }
# 400 senza campo file
# 413 oltre 5 MB

The response must be 201 with the name, 400 without a file, 413 past the limit. If you see 500, suspect the runtime first: node:fs does not run on the edge.

The EneUI catalogue indexes 111,985 components, 1,556 blocks and 12,808 icons from 1,472 libraries; the figure was measured on 1 November 2026 on ui.eneawork.it. An upload form is a primitive, not a block: the visual part comes from the catalogue, the network part you write.

Components for the visible part

Three records: the input components for the file field with an error state, the form components for the rest of the form, and the form blocks for a complete section with upload.

If the upload is a form side effect, the choice between action and handler is explained in Route Handler or Server Action. The "window is not defined" error that appears when a browser module is imported into the handler is explained in window is not defined in Next.js. For caching around the response, see the four cache levels.

The limit to budget for

A Route Handler that writes to disk does not scale past one instance. Two requests on two processes write to two different filesystems, and the user sees the file only intermittently.