UPLOADFILE DOCUMENTATION

Next.js quickstart

Connect a typed upload route and a React upload button.

1. Install the SDK

The SDK packages are included in this workspace. Use the packages from your approved package registry or workspace until a public release is published.

Terminal

pnpm add uploadfile @uploadfile/react

2. Set server environment variables

.env.local

UPLOADFILE_TOKEN=your_application_token
UPLOADFILE_API_URL=https://your-api.example.com

Keep application tokens on the server. Never prefix them with NEXT_PUBLIC_ or include them in browser bundles. Use your own configured API origin, not the UploadThing hosted service.

3. Define a file router

authenticateYourUser and saveYourFile are placeholders for your application logic. Never trust a browser-supplied user ID as authorization. Builder names remain familiar for compatibility with the upstream SDK.

TypeScript

import { createUploadthing, type FileRouter } from "uploadfile/next";

const f = createUploadthing();

export const fileRouter = {
  imageUploader: f({ image: { maxFileSize: "4MB", maxFileCount: 4 } })
    .middleware(async ({ req }) => {
      // Replace this with your application’s session validation.
      const user = await authenticateYourUser(req);
      if (!user) throw new Error("Unauthorized");
      return { userId: user.id };
    })
    .onUploadComplete(async ({ metadata, file }) => {
      // Persist the file key against your authorized user.
      await saveYourFile(metadata.userId, file.key);
      return { key: file.key };
    }),
} satisfies FileRouter;

export type AppFileRouter = typeof fileRouter;

4. Expose the route handler

Place the handler at app/api/uploadfile/route.ts and your router at app/api/uploadfile/core.ts. Your completion endpoint must be reachable by the configured callback worker.

TypeScript

import { createRouteHandler } from "uploadfile/next";
import { fileRouter } from "./core";

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

5. Add a typed upload button

TypeScript

"use client";

import { generateUploadButton } from "@uploadfile/react";
import type { AppFileRouter } from "./api/uploadfile/core";

const UploadButton = generateUploadButton<AppFileRouter>();

export function ImageUpload() {
  return (
    <UploadButton
      endpoint="imageUploader"
      url="/api/uploadfile"
      onClientUploadComplete={(files) => {
        console.log(files.map((file) => file.key));
      }}
      onUploadError={(error) => {
        // Show a useful error in your application UI.
        console.error(error.message);
      }}
    />
  );
}

Never log API keys, upload signatures, or private delivery URLs. A client callback is a UI notification, not authoritative proof of a paid or authorized operation.

Up nextFramework adapters

Uploadfile is an independently operated service. The framework SDK is forked from the MIT-licensed UploadThing SDK; UploadThing’s hosted backend is not included in that source.