---

name: uploadthing description: File upload integration using UploadThing. Use when setting up file uploads, creating file routes, implementing upload buttons/dropzones, managing uploaded files, or working with any UploadThing APIs. Covers all frameworks (Next.js, Remix, Astro, SvelteKit, SolidStart, Tanstack/Start, Nuxt, Expo), backend adapters (Express, Fastify, H3, Fetch), UTApi operations, theming, authentication, error handling, and file management.

UploadThing

The easiest way to add file uploads to your full stack TypeScript application.

When to Apply

Use this skill when:

• Setting up file uploads in a TypeScript application
• Creating file routes (endpoints) for uploads
• Implementing upload components (button, dropzone)
• Working with uploaded files (server-side operations)
• Theming upload components
• Handling authentication for uploads
• Managing errors during uploads
• Migrating between UploadThing versions

Quick Reference

Installation

# React/Next.js/Remix/Astro
npm install uploadthing @uploadthing/react

# SvelteKit
npm install uploadthing @uploadthing/svelte

# SolidStart
npm install uploadthing @uploadthing/solid

# Nuxt (Vue)
npm install uploadthing @uploadthing/nuxt

# Expo
npm install uploadthing @uploadthing/expo expo-image-picker expo-document-picker

# Backend only (Express/Fastify)
npm install uploadthing

Environment Variables

UPLOADTHING_TOKEN=...  # Required for all setups

# Nuxt specific
NUXT_UPLOADTHING_TOKEN=...

# Expo specific
EXPO_PUBLIC_SERVER_URL=...

Basic FileRouter Example

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

const f = createUploadthing();

export const uploadRouter = {
  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:", metadata.userId);
      return { uploadedBy: metadata.userId };
    }),
} satisfies FileRouter;

export type UploadRouter = typeof uploadRouter;

API Route Handler (Next.js App Router)

// app/api/uploadthing/route.ts
import { createRouteHandler } from "uploadthing/next";
import { uploadRouter } from "./core";

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

React Components

// utils/uploadthing.ts
import {
  generateUploadButton,
  generateUploadDropzone,
} from "@uploadthing/react";
import type { UploadRouter } from "~/app/api/uploadthing/core";

export const UploadButton = generateUploadButton<UploadRouter>();
export const UploadDropzone = generateUploadDropzone<UploadRouter>();

// Component usage
import { UploadButton } from "~/utils/uploadthing";

export default function Page() {
  return (
    <UploadButton
      endpoint="imageUploader"
      onClientUploadComplete={(res) => console.log("Done:", res)}
      onUploadError={(err) => console.error("Error:", err)}
    />
  );
}

Framework-Specific Guides

See detailed rules in rules/ folder:

| Framework | Setup File | Key Import | |-----------|------------|------------| | Next.js App Router | rules/nextjs-app-router.md | uploadthing/next | | Next.js Pages Router | rules/nextjs-pages-router.md | uploadthing/next-legacy | | Remix/React Router | rules/remix-router.md | uploadthing/remix | | Astro | rules/astro.md | uploadthing/server | | SvelteKit | rules/sveltekit.md | uploadthing/server | | SolidStart | rules/solidstart.md | uploadthing/server | | Tanstack/Start | rules/tanstack-start.md | uploadthing/server | | Nuxt (Vue) | rules/nuxt.md | @uploadthing/nuxt | | Expo | rules/expo.md | @uploadthing/expo | | Express | rules/express.md | uploadthing/express | | Fastify | Use Express pattern with uploadthing/fastify | | WinterCG/Fetch | rules/fetch-adapter.md | uploadthing/server |

File Router Concepts

File Types

Available file type shorthands:

• image (default max: 4MB)
• video (default max: 16MB)
• audio (default max: 8MB)
• pdf (default max: 4MB)
• text (default max: 64kB)
• blob (default max: 8MB) - any file type

You can also use MIME types: application/json, image/jpeg, etc.

Route Configuration

imageUploader: f({
  image: { maxFileSize: "4MB", maxFileCount: 4, minFileCount: 1 },
  video: { maxFileSize: "256MB", maxFileCount: 1 },
})

Options per file type:

• maxFileSize: String like "4MB", "2GB"
• maxFileCount: Number (default: 1)
• minFileCount: Number (default: 1)
• contentDisposition: "inline" | "attachment"
• acl: "public-read" | "private"

Middleware

Runs on server before upload to authenticate and tag requests:

.middleware(async ({ req, input, files }) => {
  const user = await auth(req);
  if (!user) throw new UploadThingError("Unauthorized");
  
  // Return metadata accessible in onUploadComplete
  return { userId: user.id };
})

Input Validation

Validate client-side data with Zod, Valibot, Effect, or Standard Schema:

import { z } from "zod";

f(["image"])
  .input(z.object({ folderId: z.string() }))
  .middleware(async ({ input }) => {
    // input is typed as { folderId: string }
    return { folderId: input.folderId };
  })

onUploadComplete

Run code after successful upload:

.onUploadComplete(async ({ metadata, file }) => {
  // file: { key, url, name, size, customId, ufsUrl }
  // metadata: whatever middleware returned
  
  await db.files.create({
    data: {
      key: file.key,
      url: file.url,
      userId: metadata.userId,
    },
  });
  
  // Return data sent to client onClientUploadComplete
  return { uploadedBy: metadata.userId };
})

React API

generateUploadButton

import { generateUploadButton } from "@uploadthing/react";
import type { UploadRouter } from "~/app/api/uploadthing/core";

export const UploadButton = generateUploadButton<UploadRouter>();

// Props:
// - endpoint: string (route slug)
// - input?: TInput (validated data)
// - onClientUploadComplete?: (res) => void
// - onUploadError?: (err) => void
// - onUploadBegin?: ({ file }) => void
// - onBeforeUploadBegin?: (files) => File[]
// - onUploadProgress?: (progress) => void
// - disabled?: boolean
// - config?: { mode, appendOnPaste, cn }

generateUploadDropzone

import { generateUploadDropzone } from "@uploadthing/react";

export const UploadDropzone = generateUploadDropzone<UploadRouter>();

// Additional props:
// - onDrop?: (acceptedFiles) => void
// - onDragActive?: () => void
// - onDragInactive?: () => void

useUploadThing Hook

import { generateReactHelpers } from "@uploadthing/react";

const { useUploadThing, uploadFiles, getRouteConfig } = 
  generateReactHelpers<UploadRouter>();

function CustomUploader() {
  const { startUpload, isUploading, routeConfig } = 
    useUploadThing("imageUploader", {
      onClientUploadComplete: (res) => console.log(res),
      onUploadError: (err) => console.error(err),
    });
  
  return (
    <button onClick={() => startUpload(files)} disabled={isUploading}>
      Upload
    </button>
  );
}

UTApi (Server-Side Operations)

Initialize once and reuse:

import { UTApi } from "uploadthing/server";

export const utapi = new UTApi({
  token: process.env.UPLOADTHING_TOKEN,
  logLevel: "Info",
  defaultKeyType: "fileKey", // or "customId"
});

Key Methods

| Method | Purpose | Example | |--------|---------|---------| | uploadFiles | Upload from server | utapi.uploadFiles(files) | | uploadFilesFromUrl | Upload from URL | utapi.uploadFilesFromUrl(url) | | deleteFiles | Delete files | utapi.deleteFiles(keys) | | listFiles | List uploaded files | utapi.listFiles({ limit: 100 }) | | renameFiles | Rename files | utapi.renameFiles({ fileKey, newName }) | | generateSignedURL | Get signed URL for private file | utapi.generateSignedURL(key, { expiresIn: "1h" }) | | updateACL | Change file ACL | utapi.updateACL(keys, "private") |

File Key Types

• fileKey: Auto-generated key (e.g., "uuid_filename.jpg")
• customId: Your own identifier (set via UTFiles or UTFile)

import { UTFiles } from "uploadthing/server";

// In middleware
return { 
  userId: user.id,
  [UTFiles]: files.map(f => ({ ...f, customId: myId }))
};

// Using UTFile for server uploads
import { UTFile } from "uploadthing/server";
const file = new UTFile([blob], "name.jpg", { customId: "my-id" });
await utapi.uploadFiles(file);

Theming

With TailwindCSS

Use withUt wrapper for automatic styling:

// tailwind.config.ts
import { withUt } from "uploadthing/tw";

export default withUt({
  content: ["./src/**/*.{ts,tsx}"],
  // ...rest of config
});

State Variants

<UploadButton
  className="ut-button:bg-red-500 ut-button:ut-readying:bg-red-500/50"
/>

Available variants:

• ut-button: - Button element
• ut-allowed-content: - Allowed content text
• ut-label: - Dropzone label
• ut-upload-icon: - Dropzone icon
• ut-ready: - Container when ready
• ut-readying: - Container while loading
• ut-uploading: - Container during upload

Appearance Prop

<UploadButton
  appearance={{
    container: "flex flex-col items-center",
    button: ({ ready, isUploading }) => 
      `rounded px-4 py-2 ${ready ? 'bg-blue-500' : 'bg-gray-400'}`,
    allowedContent: "text-sm text-gray-500",
  }}
/>

Content Customization

<UploadButton
  content={{
    button: ({ ready, isUploading }) => 
      isUploading ? "Uploading..." : ready ? "Upload" : "Loading...",
    allowedContent: ({ ready, fileTypes }) => 
      ready ? `Allowed: ${fileTypes.join(", ")}` : "Checking...",
  }}
/>

Authentication & Security

Protecting Uploads

import { UploadThingError } from "uploadthing/server";

.middleware(async ({ req }) => {
  const session = await auth(req);
  
  if (!session) {
    throw new UploadThingError("You must be logged in to upload");
  }
  
  return { userId: session.user.id };
})

Webhook Security

As of v6.7+, webhook callbacks are automatically verified using HMAC SHA256. No additional setup required.

IMPORTANT: Do not protect the /api/uploadthing route from public access - it's called by UploadThing's servers.

Error Handling

Server-Side

import { UploadThingError } from "uploadthing/server";

// Throw with custom message (sent to client)
throw new UploadThingError("Rate limit exceeded");

// Throw with error code
throw new UploadThingError({
  code: "FORBIDDEN",
  message: "Not allowed",
});

// Custom error formatter
const f = createUploadthing({
  errorFormatter: (err) => ({
    message: err.message,
    zodError: err.cause instanceof z.ZodError ? err.cause.flatten() : null,
  }),
});

Client-Side

<UploadButton
  endpoint="myRoute"
  onUploadError={(error) => {
    // error.message - user-facing message
    // error.data - custom error data from formatter
    console.error(error.data?.zodError?.fieldErrors);
  }}
/>

SSR Optimization

Next.js App Router

Add NextSSRPlugin to root layout for instant hydration:

// app/layout.tsx
import { NextSSRPlugin } from "@uploadthing/react/next-ssr-plugin";
import { extractRouterConfig } from "uploadthing/server";
import { uploadRouter } from "~/app/api/uploadthing/core";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <NextSSRPlugin routerConfig={extractRouterConfig(uploadRouter)} />
        {children}
      </body>
    </html>
  );
}

Next.js 15 with PPR/dynamicIO

import { connection } from "next/server";
import { Suspense } from "react";

async function UTSSR() {
  await connection();
  return <NextSSRPlugin routerConfig={extractRouterConfig(uploadRouter)} />;
}

export default function RootLayout(props) {
  return (
    <html>
      <Suspense>
        <UTSSR />
      </Suspense>
    </html>
  );
}

Regions & ACL

Available Regions

• sea1 (default) - US West - Seattle
• cle1 - US East - Ohio
• sfo1 - US West - San Francisco
• fra1 - EU Central - Frankfurt
• dub1 - EU West - Dublin
• zrh1 - EU Central - Zurich
• bom1 - Asia - Mumbai
• icn1 - Asia - Seoul
• syd1 - Asia - Sydney
• can1 - Canada - Central

Dynamic Region Selection

.middleware(async ({ req }) => {
  const region = getRegionFromRequest(req); // Your logic
  return { [experimental_UTRegion]: region };
})

Private Files

Configure default ACL in dashboard, or per-request:

imageUploader: f(
  { image: { maxFileSize: "4MB", acl: "private" } },
  { acl: "private" } // Route-level default
)

// Generate signed URL for access
const signedUrl = await utapi.generateSignedURL(fileKey, { expiresIn: "1h" });

Migration

v6 to v7 Changes

• Callback verification now automatic (v6.7+)
• generateComponents() deprecated (use generateUploadButton/generateUploadDropzone)
• awaitServerData defaults to true
• files arg removed from middleware (use UTFiles symbol)

See rules/migration-v6-v7.md for detailed migration guide.

Rule Categories

Quick reference to rule files:

Setup & Installation

• install-packages.md - Package installation
• env-variables.md - Environment setup
• tailwind-config.md - Tailwind integration

Backend (File Router)

• route-config.md - Route configuration
• middleware-auth.md - Authentication patterns
• input-validation.md - Input validation
• on-upload-complete.md - Upload completion handling
• multiple-routes.md - Organizing multiple routes

API Handlers

• nextjs-app-router.md
• nextjs-pages-router.md
• remix-router.md
• astro.md
• sveltekit.md
• solidstart.md
• tanstack-start.md
• nuxt.md
• expo.md
• express.md
• fetch-adapter.md

Frontend Components

• react-components.md
• react-hooks.md
• svelte-components.md
• solid-components.md
• vue-components.md
• expo-components.md
• component-callbacks.md
• component-config.md

UTApi

• utapi-setup.md
• utapi-upload.md
• utapi-manage.md
• utapi-urls.md

Theming

• theming-basics.md
• tailwind-theming.md
• custom-styles.md
• content-customization.md

Security & Errors

• security.md
• error-handling.md
• regions-acl.md

Performance

• ssr-optimization.md
• performance.md

Best Practices

• file-organization.md
• common-patterns.md
• testing.md
• migration-v6-v7.md

Common Patterns

Profile Picture Upload

profilePicture: f({
  image: { maxFileSize: "2MB", maxFileCount: 1 }
})
.middleware(async ({ req }) => {
  const user = await auth(req);
  if (!user) throw new UploadThingError("Unauthorized");
  return { userId: user.id };
})
.onUploadComplete(async ({ metadata, file }) => {
  await db.user.update({
    where: { id: metadata.userId },
    data: { avatarUrl: file.url }
  });
})

Multiple File Upload with Progress

<UploadDropzone
  endpoint="multipleFiles"
  uploadProgressGranularity="fine"
  onUploadProgress={({ progress }) => {
    setProgress(progress);
  }}
  onClientUploadComplete={(res) => {
    console.log("Uploaded", res.length, "files");
  }}
/>

Pre-process Files Before Upload

<UploadButton
  endpoint="imageUploader"
  onBeforeUploadBegin={(files) => {
    // Resize, rename, or filter files
    return files.map(file => 
      new File([file], `processed-${file.name}`, { type: file.type })
    );
  }}
/>

Disable Based on Input Validation

// Share validation schema
export const imageSchema = z.object({
  folderId: z.string().min(1),
});

// In component
const [folderId, setFolderId] = useState("");
const isValid = imageSchema.safeParse({ folderId }).success;

<UploadButton
  endpoint="imageUploader"
  input={{ folderId }}
  disabled={!isValid}
/>

Resources

• Official Documentation
• Dashboard
• GitHub
• Discord Support