UploadThing

https://docs.uploadthing.com
Admin
UploadThing simplifies adding file uploads to full-stack TypeScript applications. It provides easy...
Tokens:76,158
Snippets:581
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install UploadThing packages with npm

Source: https://docs.uploadthing.com/getting-started/nuxt

Install the uploadthing and @uploadthing/nuxt packages using npm.

```bash
npm install uploadthing @uploadthing/nuxt
```

--------------------------------

### Install UploadThing packages

Source: https://docs.uploadthing.com/getting-started/svelte

Install the uploadthing and @uploadthing/svelte packages using npm.

```bash
npm install uploadthing @uploadthing/svelte
```

--------------------------------

### Install UploadThing packages with npm

Source: https://docs.uploadthing.com/getting-started/solid

Install the uploadthing and @uploadthing/solid packages using npm. This is the first step in setting up UploadThing for a SolidStart project.

```bash
npm install uploadthing @uploadthing/solid
```

--------------------------------

### Full Bun adapter example

Source: https://docs.uploadthing.com/backend-adapters/custom

Complete example of a custom UploadThing adapter for Bun, including type definitions, file route builder, router with middleware and callbacks, and the request handler.

```TypeScript
import { Effect } from "effect";

import { createBuilder, makeAdapterHandler } from "uploadthing/server";
import type { FileRouter } from "uploadthing/server";

type AdapterArgs = {
  req: BunRequest;
  server: Server;
};

const f = createBuilder<AdapterArgs>();

const router = {
  imageUploader: f({ image: { maxFileSize: "16MB" } })
    .middleware((opts) => {
      opts.req;
      //   ^? BunRequest
      opts.server;
      //   ^? Server
      return { userId: "user_123" };
    })
    .onUploadError((opts) => {
      opts.req;
      //   ^? BunRequest
      opts.server;
      //   ^? Server
    })
    .onUploadComplete((opts) => {
      opts.req;
      //   ^? BunRequest
      opts.server;
      //   ^? Server
    }),
} satisfies FileRouter;

const requestHandler = makeAdapterHandler<[BunRequest, Server], AdapterArgs>(
  (req, server) => Effect.succeed({ req, server }),
  (req) => Effect.succeed(req),
  { router },
);

Bun.serve({
  routes: {
    "/api/uploadthing": requestHandler,
  },
});
```

--------------------------------

### Astro: createRouteHandler setup

Source: https://docs.uploadthing.com/backend-adapters/fetch

Sets up the UploadThing route handler for Astro. Exports the handlers as GET and POST for the framework to use.

```TypeScript
import { createRouteHandler } from "uploadthing/server";

import { uploadRouter } from "../../server/uploadthing";

const handlers = createRouteHandler({
  router: uploadRouter,
  config: { ... },
});
export { handlers as GET, handlers as POST };
```

--------------------------------

### Install uploadthing package

Source: https://docs.uploadthing.com/backend-adapters/fetch

Install the uploadthing package using npm. This is the first step in setting up UploadThing with a Fetch-compatible runtime.

```sh
npm install uploadthing
```

--------------------------------

### Install UploadThing packages

Source: https://docs.uploadthing.com/getting-started/astro

Install the required npm packages for using UploadThing with Astro and React.

```bash
npm install uploadthing @uploadthing/react
```

--------------------------------

### Install UploadThing Expo packages

Source: https://docs.uploadthing.com/getting-started/expo

Install the required packages for using UploadThing with Expo: uploadthing, @uploadthing/expo, expo-image-picker, and expo-document-picker.

```bash
npm install uploadthing @uploadthing/expo expo-image-picker expo-document-picker
```

--------------------------------

### useDocumentUploader example component (app/example-uploader.tsx)

Source: https://docs.uploadthing.com/api-reference/expo

Example component using useDocumentUploader to open a document picker and upload files. The hook accepts an endpoint and options forwarded to useUploadThing. The openDocumentPicker function takes an input matching the FileRouter schema and an onInsufficientPermissions callback.

```tsx
import { Alert, Pressable, Text, View } from "react-native";

import { useDocumentUploader } from "~/utils/uploadthing";

export function MultiUploader() {
  const { openDocumentPicker, isUploading } = useDocumentUploader("document", {
    /**
     * Any props here are forwarded to the underlying `useUploadThing` hook.
     * Refer to the React API reference for more info.
     */
    onClientUploadComplete: () => Alert.alert("Upload Completed"),
    onUploadError: (error) => Alert.alert("Upload Error", error.message),
  });

  return (
    <View>
      <Pressable
        onPress={() => {
          openDocumentPicker({
            input, // Matches the input schema from the FileRouter endpoint
            onInsufficientPermissions: () => {
              Alert.alert(
                "No Permissions",
                "You need to grant permission to your Photos to use this",
                [
                  { text: "Dismiss" },
                  { text: "Open Settings", onPress: openSettings },
                ],
              );
            },
          });
        }}
      >
        <Text>Select Document</Text>
      </Pressable>
    </View>
  );
}
```

--------------------------------

### makeAdapterHandler with options object

Source: https://docs.uploadthing.com/backend-adapters/custom

Extends the previous example with a third argument: an options object containing the router and optional config.

```TypeScript
makeAdapterHandler<[BunRequest, Server], AdapterArgs>(
  (req, server) => Effect.succeed({ req, server }),
  (req) => Effect.succeed(req),
  {
    router,
    // config: { ... },
  },
);
```

--------------------------------

### Create API route handler with createRouteHandler

Source: https://docs.uploadthing.com/getting-started/expo

Sets up the API route handler for the FileRouter using createRouteHandler. Exports GET and POST handlers. The uploadRouter is referenced from the previous example.

```ts
import { createRouteHandler } from "uploadthing/server";

const uploadRouter = { ... } satisfies FileRouter;
export type UploadRouter = typeof uploadRouter;

const handlers = createRouteHandler({
  router: uploadRouter,

  // Apply an (optional) custom config:
  // config: { ... },
})
export { handlers as GET, handlers as POST }
```

--------------------------------

### Using genUploader to create createUpload

Source: https://docs.uploadthing.com/api-reference/client

Imports genUploader from 'uploadthing/client' and the UploadRouter type, then creates a typed createUpload function. The example shows how to create an upload, pause/resume individual files, and await completion.

```TypeScript
import { genUploader } from "uploadthing/client";

import type { UploadRouter } from "~/server/uploadthing";

export const { createUpload } = genUploader<UploadRouter>();

// Create the upload. The files will start uploading immediately.
const { pauseUpload, resumeUpload, done } = createUpload("routeEndpoint", {
  files: [],
});

// Pause the upload of a file
pauseUpload(file);

// Resume the upload of a file
resumeUpload(file);

// Await the completion of all files
const files = await done();
```

--------------------------------

### uploadFiles usage example

Source: https://docs.uploadthing.com/api-reference/ut-api

Shows how to import utapi and call uploadFiles with files from a FormData in a server action. The files must be present on the server before presigned URLs are generated.

```tsx
import { utapi } from "~/server/uploadthing.ts";

async function uploadFiles(formData: FormData) {
  "use server";
  const files = formData.getAll("files");
  const response = await utapi.uploadFiles(files);
  //    ^? UploadedFileResponse[]
}

function MyForm() {
  return (
    <form action={uploadFiles}>
      <input name="files" type="file" multiple />
      <button type="submit">Upload</button>
    </form>
  );
}
```

--------------------------------

### Use createUploadThing helper in +page.svelte

Source: https://docs.uploadthing.com/getting-started/svelte

Example of using the createUploadThing helper to build a custom upload flow. It imports the helper from $lib/utils/uploadthing and calls createUploadThing with the uploader name 'imageUploader' and an onClientUploadComplete callback. The startUpload function is then used in an input's change handler to upload the selected file.

```svelte
<script lang="ts">
  import { createUploadThing } from "$lib/utils/uploadthing";

  const { startUpload } = createUploadThing("imageUploader", {
    onClientUploadComplete: () => {
      alert("Upload Completed");
    },
  });
</script>

<input
  type="file"
  on:change={async (e) => {
    const file = e.currentTarget.files?.[0];
    if (!file) return;

    // Do something with files

    // Then start the upload
    await startUpload([file]);
  }}
/>
```

--------------------------------

### Content customization example for UploadButton

Source: https://docs.uploadthing.com/concepts/theming

Example of using the `content` prop to customize the button and allowedContent elements of `UploadButton`. The callbacks receive state arguments like `ready`, `fileTypes`, and `isUploading` to conditionally render different content. Note that customizing the button means you are responsible for showing upload states like spinners.

```jsx
<UploadButton
  endpoint="mockRoute"
  content={{
    button({ ready }) {
      if (ready) return <div>Upload stuff</div>;

      return "Getting ready...";
    },
    allowedContent({ ready, fileTypes, isUploading }) {
      if (!ready) return "Checking what you allow";
      if (isUploading) return "Seems like stuff is uploading";
      return `Stuff you can upload: ${fileTypes.join(", ")}`;
    },
  }}
/>
```

--------------------------------

### Example file router with multiple routes

Source: https://docs.uploadthing.com/file-routes

Defines a file router with several routes: profilePicture, messageAttachment, strictImageAttachment, mediaPost, and withAwaitedServerData. Each route uses middleware and onUploadComplete callbacks. The router is typed with FileRouter and exported.

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

const f = createUploadthing();

export const uploadRouter = {
  // Example "profile picture upload" route - these can be named whatever you want!
  profilePicture: f(["image"])
    .middleware(({ req }) => auth(req))
    .onUploadComplete((data) => console.log("file", data)),

  // This route takes an attached image OR video
  messageAttachment: f(["image", "video"])
    .middleware(({ req }) => auth(req))
    .onUploadComplete((data) => console.log("file", data)),

  // Takes exactly ONE image up to 2MB
  strictImageAttachment: f({
    image: { maxFileSize: "2MB", maxFileCount: 1, minFileCount: 1 },
  })
    .middleware(({ req }) => auth(req))
    .onUploadComplete((data) => console.log("file", data)),

  // Takes up to 4 2mb images and/or 1 256mb video
  mediaPost: f({
    image: { maxFileSize: "2MB", maxFileCount: 4 },
    video: { maxFileSize: "256MB", maxFileCount: 1 },
  })
    .middleware(({ req }) => auth(req))
    .onUploadComplete((data) => console.log("file", data)),

  // Takes up to 4 2mb images, and the client will not resolve
  // the upload until the `onUploadComplete` resolved.
  withAwaitedServerData: f(
    { image: { maxFileSize: "2MB", maxFileCount: 4 } },
    { awaitServerData: true },
  )
    .middleware(({ req }) => auth(req))
    .onUploadComplete((data) => {
      return { foo: "bar" as const };
    }),
} satisfies FileRouter;

export type UploadRouter = typeof uploadRouter;
```

--------------------------------

### useUploadThing

Source: https://docs.uploadthing.com/api-reference/react

A hook that provides a function to start uploading, an isUploading state, and permitted file information. It is generated using generateReactHelpers.

```APIDOC
## useUploadThing

### Description
A hook that provides a function to start uploading, an `isUploading` state, and the `permittedFileInfo` which gives information about what file types, sizes and counts are allowed by the endpoint. You have to generate this hook using the `generateReactHelpers` function.

### Parameters

The first parameter is the route endpoint to upload to, and the second parameter is an options object. The endpoint arg may be a string literal or a callback function:

```ts
useUploadThing((routeRegistry) => routeRegistry.routeEndpoint, { ... })
```

Using a callback function allows `Go to Definition` on `routeEndpoint` to take you straight to your backend file route definition.

#### Options Object

- **files** (`File[]`) - Required - An array of files to upload. (Since 5.0)
- **headers** (`HeadersInit | () => HeadersInit`) - Headers to be sent along the request to request the presigned URLs. Useful for authentication outside full-stack framework setups. (Since 6.4)
- **signal** (`AbortSignal`) - An abort signal to abort the upload. (Since 6.7)
- **onClientUploadComplete** (`(UploadedFileResponse[]) => void`) - Callback function that runs **after** the serverside `onUploadComplete` callback. (Since 5.0)
- **onUploadError** (`function`) - Callback function when that runs when an upload fails. (Since 5.0)
- **onUploadAborted** (`function`) - Callback function when that runs when an upload is aborted. (Since 6.7)
- **uploadProgressGranularity** (`'all' | 'fine' | 'coarse'`) - Default: coarse - The granularity of which progress events are fired. 'all' forwards every progress event, 'fine' forwards events for every 1% of progress, 'coarse' forwards events for every 10% of progress. (Since 7.3)
- **onUploadProgress** (`function`) - Callback function that gets continuously called as the file is uploaded to the storage provider. (Since 5.1)
- **onUploadBegin** (`({ file: string }) => void`) - Callback function called after the presigned URLs have been retrieved, just before the files are uploaded to the storage provider. (Since 5.4)

### Returns

- **startUpload** (`(files: File[], input?: TInput) => void`) - Function to start the upload. `TInput` is inferred from what you've defined on the file route on the backend.
- **isUploading** (`boolean`) - Flag for if file(s) are currently uploading.
- **permittedFileTypes** (`{ slug: string, config: ExpandedRouteConfig }`) - DEPRECATED - Information on permitted file types, sizes, and counts etc.
- **routeConfig** (`ExpandedRouteConfig`) - Information on permitted file types, sizes, and counts etc. (Since 6.6)

### Example

The following example shows a simple dropzone component using the `useDropzone` and `useUploadThing` hooks. For a more complete example, take a look at our prebuilt components.
```

--------------------------------

### useImageUploader example in app/example-uploader.tsx

Source: https://docs.uploadthing.com/api-reference/expo

Shows a MultiUploader component using useImageUploader to open the native image picker and upload files. The openImagePicker call requires an input matching the FileRouter endpoint schema and a source of 'library' or 'camera', with callbacks for cancel and insufficient permissions.

```tsx
import { Alert, Pressable, Text, View } from "react-native";

import { useImageUploader } from "~/utils/uploadthing";

export function MultiUploader() {
  const { openImagePicker, isUploading } = useImageUploader("imageUploader", {
    /**
     * Any props here are forwarded to the underlying `useUploadThing` hook.
     * Refer to the React API reference for more info.
     */
    onClientUploadComplete: () => Alert.alert("Upload Completed"),
    onUploadError: (error) => Alert.alert("Upload Error", error.message),
  });

  return (
    <View>
      <Pressable
        onPress={() => {
          openImagePicker({
            input, // Matches the input schema from the FileRouter endpoint
            source: "library", // or "camera"
            onInsufficientPermissions: () => {
              Alert.alert(
                "No Permissions",
                "You need to grant permission to your Photos to use this",
                [
                  { text: "Dismiss" },
                  { text: "Open Settings", onPress: openSettings },
                ],
              );
            },
          });
        }}
      >
        <Text>Select Image</Text>
      </Pressable>
    </View>
  );
}
```

--------------------------------

### createUpload

Source: https://docs.uploadthing.com/api-reference/client

Creates a resumable upload. Allows starting, pausing, and resuming uploads. Returns an object with pauseUpload, resumeUpload, and done methods.

```APIDOC
## createUpload

### Description
Create a resumable upload. Resumable uploads allows you to start an upload, pause it, and then resume it at a later time. As long as the presigned URL is valid, you can continue the upload from where it left off.

### Method
Function

### Signature
```ts
const { pauseUpload, resumeUpload, done } = createUpload(routeEndpoint, options);
```

### Parameters
- **files** (`File[]`) - Required - An array of files to upload.
- **input** (`TInput`) - Optional - Input JSON data matching your validator set on the FileRoute to send with the request.
- **headers** (`HeadersInit | () => HeadersInit`) - Optional - Headers to be sent along the request to request the presigned URLs. Useful for authentication outside full-stack framework setups.
- **onUploadProgress** (`(progress) => void`) - Optional - Callback function that gets continuously called as the file is uploaded to the storage provider.

### Returns
- **pauseUpload** (`(file?: File) => void`) - Pause the upload of a file. If no file is provided, all files will be paused.
- **resumeUpload** (`(file?: File) => void`) - Resume the upload of a file. If no file is provided, all files will be resumed.
- **done** (`(file?: File) => Promise<MaybeArray<UploadedFileResponse>>`) - Await the completion of the upload of a file. If no file is provided, all files will be awaited. The returned object is the same as the one returned by `uploadFiles`. If a file is provided, the function returns an object, else it returns an array.

### Example
```ts
import { genUploader } from "uploadthing/client";
import type { UploadRouter } from "~/server/uploadthing";

export const { createUpload } = genUploader<UploadRouter>();

// Create the upload. The files will start uploading immediately.
const { pauseUpload, resumeUpload, done } = createUpload("routeEndpoint", {
  files: [],
});

// Pause the upload of a file
pauseUpload(file);

// Resume the upload of a file
resumeUpload(file);

// Await the completion of all files
const files = await done();
```

### Notes
- Resumable uploads are currently not supported on React Native due to difficulties integrating with React Native's `Blob` implementation.

```

--------------------------------

### Create API route handler for UploadThing

Source: https://docs.uploadthing.com/getting-started/solid

Create an API route in src/routes/api/uploadthing.ts that uses createRouteHandler from uploadthing/server. The handler is wired to GET and POST events. The file path can be any route, but /api/uploadthing is recommended.

```ts
import type { APIEvent } from "@solidjs/start/server";

import { createRouteHandler } from "uploadthing/server";

import { uploadRouter } from "~/server/uploadthing";

const handler = createRouteHandler({
  router: uploadRouter,
});

export const GET = (event: APIEvent) => handler(event.request);
export const POST = (event: APIEvent) => handler(event.request);
```

--------------------------------

### Define a FileRouter with imageUploader route

Source: https://docs.uploadthing.com/getting-started/solid

Create a FileRouter in src/server/uploadthing.ts. This example defines a single FileRoute 'imageUploader' with max file size 4MB and max file count 1. It includes middleware for authentication and an onUploadComplete callback. The middleware returns metadata accessible in onUploadComplete, and the return value of onUploadComplete is sent to the client-side callback.

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

const f = createUploadthing();

const auth = (req: Request) => ({ id: "fakeId" }); // Fake auth function

export const uploadRouter = {
  // Define as many FileRoutes as you like, each with a unique routeSlug
  imageUploader: f({
    image: {
      /**
       * For full list of options and defaults, see the File Route API reference
       * @see https://docs.uploadthing.com/file-routes#route-config
       */
      maxFileSize: "4MB",
      maxFileCount: 1,
    },
  })
    // Set permissions and file types for this FileRoute
    .middleware(async ({ req }) => {
      // This code runs on your server before upload
      const user = await auth(req);

      // If you throw, the user will not be able to upload
      if (!user) throw new UploadThingError("Unauthorized");

      // Whatever is returned here is accessible in onUploadComplete as `metadata`
      return { userId: user.id };
    })
    .onUploadComplete(async ({ metadata, file }) => {
      // This code RUNS ON YOUR SERVER after upload
      console.log("Upload complete for userId:", metadata.userId);

      console.log("file url", file.ufsUrl);

      // !!! Whatever is returned here is sent to the clientside `onClientUploadComplete` callback
      return { uploadedBy: metadata.userId };
    }),
} satisfies FileRouter;

export type UploadRouter = typeof uploadRouter;
```

--------------------------------

### generateReactNativeHelpers setup in utils/uploadthing.tsx

Source: https://docs.uploadthing.com/api-reference/expo

Creates the useImageUploader and useDocumentUploader hooks by calling generateReactNativeHelpers with your UploadRouter type. The url option defaults to process.env.EXPO_PUBLIC_SERVER_URL, and in dev Expo.debuggerHost is also tried.

```tsx
import { generateReactNativeHelpers } from "@uploadthing/expo";

import type { UploadRouter } from "~/app/api/uploadthing+api";

export const { useImageUploader, useDocumentUploader } =
  generateReactNativeHelpers<UploadRouter>({
    /**
     * Your server url.
     * @default process.env.EXPO_PUBLIC_SERVER_URL
     * @remarks In dev we will also try to use Expo.debuggerHost
     */
    url: "https://my-server.com",
  });
```

--------------------------------

### Dynamic region selection middleware with experimental_UTRegion

Source: https://docs.uploadthing.com/concepts/regions-acl

Middleware example that tags upload metadata with the experimental_UTRegion key to select a region based on the user's continent. Uses a mapping from continent codes to region aliases, with a fallback to 'sea1'. Requires the feature to be enabled in private beta.

```TypeScript
export const uploadRouter = {
  anyPrivate: fileRoute({
    blob: { maxFileSize: "256MB", maxFileCount: 10, acl: "public-read" },
  })
    .input(z.object({}))
    .middleware(async (opts) => {
      /**
       * Simple example using continent code to select region.
       *
       * Europe and Africa will be routed to Frankfurt,
       * Asia to Mumbai (India), and the rest to Virginia (US-East).
       *
       * You can do this selection however you like.
       */
      const region =
        (
          {
            AF: "fra1",
            AN: "sea1",
            AS: "bom1",
            EU: "fra1",
            NA: "sea1",
            OC: "sea1",
            SA: "sea1",
          } as const
        )[opts.req.headers.get("x-vercel-ip-continent")?.toUpperCase()] ??
        "sea1"; // Fallback

      return { [experimental_UTRegion]: region }; // <-- Tag the upload with the selected region
    })
    .onUploadComplete(async (opts) => {
      console.log("Upload complete", opts.file);
    }),
} satisfies FileRouter;
```

--------------------------------

### genUploader now returns an object with uploadFiles and createUpload

Source: https://docs.uploadthing.com/v7

In v7, genUploader returns an object with two functions: uploadFiles and createUpload. The example shows the old direct assignment and the new destructuring.

```ts
import { genUploader } from 'uploadthing/client'
import type { UploadRouter } from '~/uploadthing/router'

const uploadFiles = genUploader<UploadRouter>() 
const { uploadFiles, createUpload } = genUploader<UploadRouter>() 
```

--------------------------------

### Define a FileRouter in server/uploadthing.ts

Source: https://docs.uploadthing.com/getting-started/nuxt

Minimal FileRouter example with a single 'imageUploader' route. It uses createUploadthing from 'uploadthing/h3', defines a fake auth function, and exports the router as 'uploadRouter' and its type as 'UploadRouter'. The middleware runs on the server before upload and returns metadata, while onUploadComplete runs after upload and logs the file URL.

```TypeScript
import type { H3Event } from "h3";

import { createUploadthing } from "uploadthing/h3";
import type { FileRouter } from "uploadthing/h3";

const f = createUploadthing();

const auth = (ev: H3Event) => ({ id: "fakeId" }); // Fake auth function

// FileRouter for your app, can contain multiple FileRoutes
export const uploadRouter = {
  // Define as many FileRoutes as you like, each with a unique routeSlug
  imageUploader: f({
    image: {
      /**
       * For full list of options and defaults, see the File Route API reference
       * @see https://docs.uploadthing.com/file-routes#route-config
       */
      maxFileSize: "4MB",
      maxFileCount: 1,
    },
  })
    // Set permissions and file types for this FileRoute
    .middleware(async ({ event }) => {
      // This code runs on your server before upload
      const user = await auth(event);

      // If you throw, the user will not be able to upload
      if (!user) throw new Error("Unauthorized");

      // Whatever is returned here is accessible in onUploadComplete as `metadata`
      return { userId: user.id };
    })
    .onUploadComplete(async ({ metadata, file }) => {
      // This code RUNS ON YOUR SERVER after upload
      console.log("Upload complete for userId:", metadata.userId);

      console.log("file url", file.ufsUrl);
    }),
} satisfies FileRouter;

export type UploadRouter = typeof uploadRouter;
```

--------------------------------

### Mount UploadButton in src/routes/index.tsx

Source: https://docs.uploadthing.com/getting-started/solid

Imports the UploadButton component from the utils module and renders it with the endpoint prop set to 'imageUploader'. This is the final step in the Solid getting started guide.

```tsx
import { UploadButton } from "~/utils/uploadthing";

export default function Home() {
  return <UploadButton endpoint="imageUploader" />;
}
```

--------------------------------

### Re-export createRouteHandler handler as GET and POST

Source: https://docs.uploadthing.com/v7

If your framework expects named exports for each method, you can re-export the single handler as GET and POST. This example shows the re-export pattern.

```ts
import { createRouteHandler } from "uploadthing/server";

import { uploadRouter } from "~/uploadthing/router";

const handler = createRouteHandler({ router, config });
export { handler as GET, handler as POST };
```

--------------------------------

### Next.js adapter createRouteHandler still returns named exports

Source: https://docs.uploadthing.com/v7

The Next.js adapter from 'uploadthing/next' still returns named exports for GET and POST methods. This example shows the destructuring pattern.

```ts
import { createRouteHandler } from "uploadthing/next";

import { uploadRouter } from "~/uploadthing/router";

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

--------------------------------

### Constructor

Source: https://docs.uploadthing.com/api-reference/ut-api

Initializes a new UTApi instance with optional configuration options.

```APIDOC
## Constructor

### Description
Initializes a new UTApi instance. Prior to v5.7, UTApi was exported as an object called `utapi` without custom initialization support.

### Method
Constructor

### Endpoint
`new UTApi(options?)`

### Parameters
#### Options (all optional)
- **fetch** (`FetchEsque`) - Optional - Provide a custom fetch function. (Since 5.7)
- **token** (`string`) - Optional - Your UploadThing token. Defaults to `env.UPLOADTHING_TOKEN`. (Since 7.0)
- **logLevel** (`Error | Warning | Info | Debug | Trace`) - Optional - Enable more verbose logging. Default: Info. (Since 7.0)
- **logFormat** (`json | logFmt | structured | pretty`) - Optional - What format log entries should be in. Default: pretty in development, else json. (Since 7.1)
- **defaultKeyType** (`'fileKey' | 'customId'`) - Optional - Set the default key type for file operations. (Since 6.4)
- **apiUrl** (`string`) - Optional - The URL of the UploadThing API. Defaults to `https://api.uploadthing.com`. (Since 7.0)
- **ingestUrl** (`string`) - Optional - The URL of the UploadThing Ingest API. Will be decoded from the `token` if not specified. (Since 7.0)

### Request Example
```ts
import { UTApi } from "uploadthing/server";

export const utapi = new UTApi({
  // ...options,
});
```

### Response
No response body. The constructor returns a UTApi instance.
```

--------------------------------

### createRouteHandler from uploadthing/server returns a single handler

Source: https://docs.uploadthing.com/v7

In v7, createRouteHandler from 'uploadthing/server' returns a single handler for all methods instead of separate GET and POST functions. The example shows the old destructuring and the new single handler assignment.

```ts
import { createRouteHandler } from "uploadthing/server";

import { uploadRouter } from "~/uploadthing/router";

const { GET, POST } = createRouteHandler({ router }); 
const handler = createRouteHandler({ router }); 
```

--------------------------------

### UploadButton usage in app/example-uploader.tsx

Source: https://docs.uploadthing.com/api-reference/react

Example of using the UploadButton component with a custom file router. It includes handlers for upload completion, errors, preprocessing files before upload, and upload start. The component is typed with OurFileRouter and uses the 'imageUploader' endpoint.

```tsx
import { UploadButton } from "@uploadthing/react";

import { OurFileRouter } from "./api/uploadthing/core";

export const OurUploadButton = () => (
  <UploadButton<OurFileRouter>
    endpoint="imageUploader"
    onClientUploadComplete={(res) => {
      // Do something with the response
      console.log("Files: ", res);
      alert("Upload Completed");
    }}
    onUploadError={(error: Error) => {
      // Do something with the error.
      alert(`ERROR! ${error.message}`);
    }}
    onBeforeUploadBegin={(files) => {
      // Preprocess files before uploading (e.g. rename them)
      return files.map(
        (f) => new File([f], "renamed-" + f.name, { type: f.type }),
      );
    }}
    onUploadBegin={(name) => {
      // Do something once upload begins
      console.log("Uploading: ", name);
    }}
  />
);
```

--------------------------------

### getFileUrls: Get URLs for files (deprecated)

Source: https://docs.uploadthing.com/api-reference/ut-api

Returns URLs for a single fileKey or an array of fileKeys. This method is deprecated and will be removed in a future version; refer to the 'Accessing Files' guide for alternatives. The keyType option defaults to "fileKey" and is available since version 6.4.

```TypeScript
import { utapi } from "~/server/uploadthing.ts";

const oneUrl = await utapi.getFileUrls(
  "2e0fdb64-9957-4262-8e45-f372ba903ac8_image.jpg",
);
const multipleUrls = await utapi.getFileUrls([
  "2e0fdb64-9957-4262-8e45-f372ba903ac8_image.jpg",
  "1649353b-04ea-48a2-9db7-31de7f562c8d_image2.jpg",
]);
```

--------------------------------

### Create UTFile and upload with UTApi

Source: https://docs.uploadthing.com/api-reference/server

Shows how to instantiate UTApi, create a UTFile with a customId, and upload it using uploadFiles. The UTFile constructor takes parts, a name, and optional options including type, customId, and lastModified.

```TypeScript
import { UTApi, UTFile } from "uploadthing/server";

const utapi = new UTApi();

const file = new UTFile(["foo"], "foo.txt", { customId: "foo" });
const response = await utapi.uploadFiles([file]);
```

--------------------------------

### Bun server with /api/hello route

Source: https://docs.uploadthing.com/backend-adapters/custom

A simple Bun server that listens on /api/hello and returns a JSON response. Demonstrates the Bun request handler signature (req, server) and Response object.

```TypeScript
Bun.serve({
  routes: {
    "/api/hello": (req, server) => Response.json({ message: "Hello, world!" }),
  },
});
```

--------------------------------

### Configure UTApi via environment variable UPLOADTHING_LOG_LEVEL

Source: https://docs.uploadthing.com/v7

Shows that configuration options can be passed as environment variables in constant case prefixed with UPLOADTHING. The options object takes precedence if both are provided.

```ts
const api = new UTApi({
  logLevel: 'Info',
})

// is the same as
process.env.UPLOADTHING_LOG_LEVEL = 'Info'
const api = new UTApi()
```

--------------------------------

### Create H3 event handlers (Vanilla H3)

Source: https://docs.uploadthing.com/backend-adapters/h3

Sets up an H3 app and router, mounting the UploadThing route handler at '/api/uploadthing'. The router is created with createRouteHandler from 'uploadthing/h3'.

```ts
import { createApp, createRouter } from "h3";

import { createRouteHandler } from "uploadthing/h3";
import { uploadRouter } from "./router";

const app = createApp();
const router = createRouter();

router.use(
  "/api/uploadthing",
  createRouteHandler({
    router: uploadRouter,
    config: { ... },
  })
);

app.use(router);

export { app }; // Run server with e.g. `listhen`
```

--------------------------------

### UploadDropzone component example in app/example-uploader.tsx

Source: https://docs.uploadthing.com/api-reference/react

Example of using the UploadDropzone component with the OurFileRouter type. It includes handlers for upload completion, errors, upload begin, and file drop. The endpoint is set to 'withoutMdwr'.

```tsx
import { UploadDropzone } from "@uploadthing/react";

import { OurFileRouter } from "./api/uploadthing/core";

export const OurUploadDropzone = () => (
  <UploadDropzone<OurFileRouter>
    endpoint="withoutMdwr"
    onClientUploadComplete={(res) => {
      // Do something with the response
      console.log("Files: ", res);
      alert("Upload Completed");
    }}
    onUploadError={(error: Error) => {
      alert(`ERROR! ${error.message}`);
    }}
    onUploadBegin={(name) => {
      // Do something once upload begins
      console.log("Uploading: ", name);
    }}
    onDrop={(acceptedFiles) => {
      // Do something with the accepted files
      console.log("Accepted files: ", acceptedFiles);
    }}
  />
);
```

--------------------------------

### Error Formatter with Zod

Source: https://docs.uploadthing.com/concepts/error-handling

Example of using errorFormatter to return Zod validation errors to the client.

```APIDOC
## Error Formatter with Zod

### Description
Example of using errorFormatter to return Zod validation errors to the client.

### Code Example
```ts
import * as z from "zod";

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

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

export const uploadRouter = {
  withInput: f(["image"]).input(z.object({ foo: z.string() })),
  //  ...
} satisfies FileRouter;
```
```

--------------------------------

### UploadDropzone Component Usage

Source: https://docs.uploadthing.com/api-reference/react

Example of using the UploadDropzone component from @uploadthing/react with an endpoint and event handlers.

```APIDOC
## UploadDropzone

### Description
A `react-dropzone` powered dropzone that lets you drag and drop files to upload. The default dropzone is shown below. See Theming on how to customize it.

### Usage
Import `UploadDropzone` from `@uploadthing/react` and use it with your file router.

### Example
```tsx
import { UploadDropzone } from "@uploadthing/react";

import { OurFileRouter } from "./api/uploadthing/core";

export const OurUploadDropzone = () => (
  <UploadDropzone<OurFileRouter>
    endpoint="withoutMdwr"
    onClientUploadComplete={(res) => {
      // Do something with the response
      console.log("Files: ", res);
      alert("Upload Completed");
    }}
    onUploadError={(error: Error) => {
      alert(`ERROR! ${error.message}`);
    }}
    onUploadBegin={(name) => {
      // Do something once upload begins
      console.log("Uploading: ", name);
    }}
    onDrop={(acceptedFiles) => {
      // Do something with the accepted files
      console.log("Accepted files: ", acceptedFiles);
    }}
  />
);
```

### Props
- **endpoint** (string) - Required - The endpoint key from your file router.
- **onClientUploadComplete** (function) - Optional - Callback fired when the upload completes. Receives the response.
- **onUploadError** (function) - Optional - Callback fired when an upload error occurs. Receives an Error object.
- **onUploadBegin** (function) - Optional - Callback fired when an upload begins. Receives the file name.
- **onDrop** (function) - Optional - Callback fired when files are dropped. Receives the accepted files.
```

--------------------------------

### Import UploadThing CSS in root layout

Source: https://docs.uploadthing.com/faq

Add this import to your root layout.tsx or _app.tsx to ensure UploadThing components are styled.

```tsx
import "@uploadthing/react/styles.css";
```

--------------------------------

### createRouteHandler with Next.js App Router

Source: https://docs.uploadthing.com/api-reference/server

Import createRouteHandler from 'uploadthing/next' and pass the uploadRouter. Exports GET and POST handlers.

```TypeScript
import { createRouteHandler } from "uploadthing/next";
import { uploadRouter } from "~/server/uploadthing.ts";

export const { GET, POST } = createRouteHandler({
  router: uploadRouter,
  // config: { ... },
});
```

--------------------------------

### Catching Errors on the Client

Source: https://docs.uploadthing.com/concepts/error-handling

Example of using onUploadError to catch errors and access the formatted error data on the client.

```APIDOC
## Catching Errors on the Client

### Description
Example of using onUploadError to catch errors and access the formatted error data on the client.

### Code Example
```tsx
<UploadButton
  endpoint="withInput"
  input={{ foo: userInput }}
  onUploadError={(error) => {
    console.log("Error: ", error);
    const fieldErrors = error.data?.zodError?.fieldErrors;
    //                              ^? typeToFlattenedError
    setError(fieldErrors.foo[0] ?? "");
  }}
/>
```
```

--------------------------------

### Use main entrypoint instead of @uploadthing/react/hooks

Source: https://docs.uploadthing.com/v7

The `@uploadthing/react/hooks` entrypoint has been removed. Import `generateReactHelpers` from the main entrypoint instead.

```typescript
import { generateReactHelpers } from '@uploadthing/react/hooks'
```

```typescript
import { generateReactHelpers } from '@uploadthing/react'
```

--------------------------------

### Error Formatter with UploadThingError

Source: https://docs.uploadthing.com/concepts/error-handling

Example of using errorFormatter and throwing UploadThingError in middleware to control client error messages.

```APIDOC
## Error Formatter with UploadThingError

### Description
Demonstrates how to customize error formatting and throw UploadThingError in middleware to send specific error messages to the client.

### Code Example
```ts
import {
  createUploadthing,
  UploadThingError,
  type FileRouter,
} from "uploadthing/server";

const f = createUploadthing();

const auth = (req: Request) => ({ id: "fakeId" });

export const ourFileRouter = {
  imageUploader: f({ image: { maxFileSize: "4MB" } })
    .middleware(async ({ req }) => {
      const user = await auth(req);

      if (!user) throw new Error(`Cant find user from req: ${req.toString()}`); // client onError will get "Failed to run middleware"
      if (!user.id) throw new UploadThingError("No user ID"); // client onError will get "No user ID"

      return { userId: user.id };
    })
    .onUploadComplete(async ({ metadata, file }) => {
      console.log("Upload complete for userId:", metadata.userId);

      console.log("file url", file.url);

      return { uploadedBy: metadata.userId };
    }),
} satisfies FileRouter;

export type OurFileRouter = typeof ourFileRouter;
```
```

--------------------------------

### Add NUXT_UPLOADTHING_TOKEN environment variable

Source: https://docs.uploadthing.com/getting-started/nuxt

Set the NUXT_UPLOADTHING_TOKEN environment variable. The NUXT_ prefix is important.

```bash
NUXT_UPLOADTHING_TOKEN=... # A token for interacting with the SDK
# 👆 NUXT_ prefix is **important**
```

--------------------------------

### GET /api/uploadthing

Source: https://docs.uploadthing.com/uploading-files

Retrieves endpoint metadata for the UploadThing API. This endpoint is used by the frontend SDK to fetch configuration information.

```APIDOC
## GET /api/uploadthing

### Description
Retrieves endpoint metadata for the UploadThing API. This endpoint is used by the frontend SDK to fetch configuration information.

### Method
GET

### Endpoint
/api/uploadthing

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **EndpointMetadata** (object) - The metadata for the endpoint.

#### Response Example
```json
{
  "endpointMetadata": {}
}
```
```

--------------------------------

### Set UPLOADTHING_TOKEN environment variable

Source: https://docs.uploadthing.com/backend-adapters/fetch

Add the UPLOADTHING_TOKEN environment variable to your project. The token is required for interacting with the UploadThing SDK and can be obtained from the UploadThing dashboard.

```bash
UPLOADTHING_TOKEN=... # A token for interacting with the SDK
```

--------------------------------

### Create file route builder with createBuilder

Source: https://docs.uploadthing.com/backend-adapters/custom

Imports createBuilder from uploadthing/server and creates a file route builder f with the AdapterArgs type.

```TypeScript
import { createBuilder } from "uploadthing/server";

const f = createBuilder<AdapterArgs>();
```

--------------------------------

### Add UploadThing's styles with withUt Tailwind helper

Source: https://docs.uploadthing.com/getting-started/astro

Wrap your Tailwind config with the withUt helper from uploadthing/tw. This is for Tailwind v3; other versions may have different instructions.

```TSX
import { withUt } from "uploadthing/tw";

export default withUt({
  // Your existing Tailwind config
  content: ["./src/**/*.{ts,tsx,mdx}"],
  ...
});
```

--------------------------------

### makeAdapterHandler with two functions

Source: https://docs.uploadthing.com/backend-adapters/custom

Shows the first two arguments to makeAdapterHandler: functions that return adapter args and a web standard Request. Uses Effect.succeed.

```TypeScript
import { makeAdapterHandler } from "uploadthing/server";

makeAdapterHandler<[BunRequest, Server], AdapterArgs>(
  (req, server) => Effect.succeed({ req, server }),
  (req) => Effect.succeed(req),
  // ...
);
```

--------------------------------

### Elysia: createRouteHandler with Elysia server

Source: https://docs.uploadthing.com/backend-adapters/fetch

Integrates the UploadThing route handler with an Elysia server. Maps GET and POST requests to /api/uploadthing to the handler.

```TypeScript
import { Elysia } from "elysia";

import { createRouteHandler } from "uploadthing/server";

import { uploadRouter } from "./uploadthing.ts";

const handlers = createRouteHandler({
  router: uploadRouter,
  config: { ... },
});

new Elysia()
  .get("/api", () => "Hello from Elysia!")
  .get("/api/uploadthing", (ev) => handlers(ev.request))
  .post("/api/uploadthing", (ev) => handlers(ev.request))
  .listen(3000, (server) => {
    console.log(`Server listening on port ${server.port}`);
  });
```

--------------------------------

### Endpoint callback usage

Source: https://docs.uploadthing.com/api-reference/react

Shows how to pass a callback function to the endpoint prop, enabling 'Go to Definition' navigation to the backend route definition.

```ts
await uploadFiles((routeRegistry) => routeRegistry.routeEndpoint, { ... })
```

--------------------------------

### Create Astro API route in src/pages/api/uploadthing.ts

Source: https://docs.uploadthing.com/getting-started/astro

Sets up an API route using createRouteHandler to handle upload requests, exporting GET and POST handlers.

```ts
import { createRouteHandler } from "uploadthing/server";

import { ourFileRouter } from "~/server/uploadthing";

// Export routes for Next App Router
const handlers = createRouteHandler({
  router: ourFileRouter,
  config: {
    token: import.meta.env.UPLOADTHING_TOKEN,
  },
});
export { handlers as GET, handlers as POST };
```

--------------------------------

### Create API route handler in src/routes/api/uploadthing/+server.ts

Source: https://docs.uploadthing.com/getting-started/svelte

Exposes the FileRouter via a server route handler. Uses the UPLOADTHING_TOKEN from environment variables and exports GET and POST handlers.

```ts
import { env } from "$env/dynamic/private";
import { ourFileRouter } from "$lib/server/uploadthing";

import { createRouteHandler } from "uploadthing/server";

const handlers = createRouteHandler({
  router: ourFileRouter,
  config: {
    token: env.UPLOADTHING_TOKEN,
  },
});

export { handlers as GET, handlers as POST };
```

--------------------------------

### Import default stylesheet when not using withUt

Source: https://docs.uploadthing.com/concepts/theming

If you're not wrapping your config with withUt, you have to import the default stylesheet into your app. Otherwise, components will not look right.

```ts
import "@uploadthing/react/styles.css";

// ...
```

--------------------------------

### useUploadThing with callback endpoint

Source: https://docs.uploadthing.com/api-reference/react

Shows how to pass a callback function as the endpoint argument to useUploadThing, enabling 'Go to Definition' on routeEndpoint to navigate to the backend file route definition.

```typescript
useUploadThing((routeRegistry) => routeRegistry.routeEndpoint, { ... })
```
Tokens:
Raw