The Complete Production SOP: How to Deploy and Run UploadThing Type-Safe Fullstack File Upload Infrastructure in Autonomous AI Agents

---
name: "uploadthing-fullstack-file-uploads"
description: "Add file uploads to Next.js/React with type-safe server route handlers and S3-backed storage."
metadata:
  author: "Ping.gg"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "setup uploadthing nextjs"
  - "create filerouter uploadthing"
  - "uploadbutton client uploadthing"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# UploadThing Type-Safe Fullstack File Upload Infrastructure

Configures UploadThing: creating FileRouter in app/api/uploadthing/core.ts, middleware auth checks, onUploadComplete callbacks, drop-in client components (<UploadButton />, <UploadDropzone />), and automatic file cleanup.

import { createUploadthing, type FileRouter } from "uploadthing/next";
import { UploadThingError } from "uploadthing/server";

const f = createUploadthing();

const auth = async (req: Request) => ({ id: "usr_mock_123" }); // Replace with actual session auth

export const ourFileRouter = {
  imageUploader: f({ image: { maxFileSize: "4MB", maxFileCount: 1 } })
    .middleware(async ({ req }) => {
      const user = await auth(req);
      if (!user) throw new UploadThingError("Unauthorized");
      return { userId: user.id };
    })
    .onUploadComplete(async ({ metadata, file }) => {
      console.log("Uploaded by user:", metadata.userId);
      console.log("Direct file URL:", file.url);
      return { uploadedBy: metadata.userId, url: file.url };
    }),
} satisfies FileRouter;

export type OurFileRouter = typeof ourFileRouter;

import { createRouteHandler } from "uploadthing/next";
import { ourFileRouter } from "./core";

export const { GET, POST } = createRouteHandler({
  router: ourFileRouter,
});

"use client";

import { UploadDropzone } from "@uploadthing/react";
import type { OurFileRouter } from "@/app/api/uploadthing/core";

export function ImageUploader() {
  return (
    <UploadDropzone<OurFileRouter, "imageUploader">
      endpoint="imageUploader"
      onClientUploadComplete={(res) => {
        console.log("Upload successful:", res);
      }}
      onUploadError={(error: Error) => {
        console.error(`Upload error: ${error.message}`);
      }}
    />
  );
}