uploadthing is a platform for storing files in the cloud. It’s a great alternative to AWS S3 and it’s free for small projects. Here’s how to switch the default storage provider to uploadthing.

​
1. Update the environment variables

Next, add the environment variables to your .env.local file:
apps/app/.env
// Add this:
UPLOADTHING_TOKEN=""

​
2. Update the existing storage files

Update the index.ts and client.ts to use the new uploadthing packages: 
export * from './providers/uploadthing';

​
3. Create new SSR file

We’ll also need to create a new file for the storage package to handle the Tailwind CSS classes and SSR.
packages/storage/ssr.ts
export { NextSSRPlugin as StorageSSRPlugin } from '@uploadthing/react/next-ssr-plugin';

​
4. Create a file router in your app

Create a new file in your app’s lib directory to define the file router. This file will be used to define the file routes for your app, using your Auth package to get the current user.
apps/app/app/lib/upload.ts
import { currentUser } from '@repo/auth/server';
import { type FileRouter, UploadError, storage } from '@repo/storage';
  
export const router: FileRouter = {
  imageUploader: storage({
    image: {
      maxFileSize: '4MB',
      maxFileCount: 1,
    },
  })
    .middleware(async () => {
      const user = await currentUser();

      if (!user) {
        throw new UploadError('Unauthorized');
      }

      return { userId: user.id };
    })
    .onUploadComplete(({ metadata, file }) => ({ uploadedBy: metadata.userId }),
};

​
5. Create a route handler

Create a new route handler in your app’s api directory to handle the file routes.
apps/app/app/api/upload/route.ts
import { router } from '@/app/lib/upload';
import { createRouteHandler } from '@repo/storage';

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

​
6. Update your root layout

Update your root layout to include the StorageSSRPlugin. This will add SSR hydration and avoid a loading state on your upload button.
apps/app/app/layout.tsx
import '@repo/design-system/styles/globals.css';
import { DesignSystemProvider } from '@repo/design-system';
import { fonts } from '@repo/design-system/lib/fonts';
import { extractRouterConfig } from '@repo/storage';
import { StorageSSRPlugin } from '@repo/storage/ssr';
import type { ReactNode } from 'react';
import { router } from './lib/upload';

type RootLayoutProperties = {
  readonly children: ReactNode;
};

const RootLayout = ({ children }: RootLayoutProperties) => (
  <html lang="en" className={fonts} suppressHydrationWarning>
    <body>
      <StorageSSRPlugin routerConfig={extractRouterConfig(router)} />
      <DesignSystemProvider>{children}</DesignSystemProvider>
    </body>
  </html>
);

export default RootLayout;

​
7. Update your Tailwind CSS

Update your design system’s globals.css file to include the following:
packages/design-system/styles/globals.css
@import "uploadthing/tw/v4";
@source "../node_modules/@uploadthing/react/dist";

​
8. Create your upload button

Create a new component for your upload button. This will use the generateUploadButton function to create a button that will upload files to the imageUploader endpoint.
apps/app/app/(authenticated)/components/upload-button.tsx
'use client';

import type { router } from '@/app/lib/upload';
import { generateUploadButton } from '@repo/storage/client';
import { toast } from 'sonner';

const UploadButton = generateUploadButton<typeof router>();

export const UploadForm = () => (
  <UploadButton
    endpoint="imageUploader"
    onClientUploadComplete={(res) => {
      // Do something with the response
      console.log('Files: ', res);
      toast.success('Upload Completed');
    }}
    onUploadError={(error: Error) => {
      toast.error(`ERROR! ${error.message}`);
    }}
  />
);
Now you can import this component into your app and use it as a regular component.

​
9. Advanced configuration

uploadthing is a powerful platform that offers a lot of advanced configuration options. You can learn more about them in the uploadthing documentation.

File Routes

Learn how to define file routes

Security

How to protect different parts of the UploadThing flow.