UploadThing API Migration: Fixing Deprecation Warnings

When upgrading your UploadThing API from version 7.7.4, you’ll need to replace deprecated file.url and file.appUrl properties with new URL alternatives to resolve deprecation warnings. This migration ensures compatibility with the latest API version and follows current best practices for file URL handling in UploadThing.

Contents

• Understanding UploadThing API Deprecation Warnings
• Identifying Deprecated Properties: file.url and file.appUrl
• Migration Guide: Upgrading from UploadThing 7.7.4
• Updated Code Examples for the New API
• Best Practices for File URL Handling in UploadThing
• Sources
• Conclusion

Understanding UploadThing API Deprecation Warnings

UploadThing is a file upload service designed as an easier and safer alternative to S3 for developers. When you see deprecation warnings for file.url and file.appUrl in your logs or console after upgrading to a recent version, it’s because these properties have been replaced with more secure and consistent alternatives.

Why does this matter? Well, the old approach created potential security vulnerabilities and inconsistencies across different environments. The new API addresses these issues by providing better access control and more predictable URL behavior. You might be wondering why your existing code suddenly breaks—but this is actually a good thing. The team at UploadThing is proactively improving their service to ensure your file uploads remain secure and reliable across all platforms.

The deprecation warnings serve as a heads-up that your code needs updating before these properties are completely removed in future versions. Ignoring these warnings could lead to your file URLs breaking when you upgrade to newer versions of the UploadThing API.

Identifying Deprecated Properties: file.url and file.appUrl

The two properties causing deprecation warnings are file.url and file.appUrl. In your current code, you might be using them like this:

// Old approach - now deprecated
const fileUrl = file.url;
const publicUrl = file.appUrl;

These properties were originally designed to provide direct access to uploaded files, but they’ve been replaced with new, more secure alternatives. The file.url property provided a direct link to the file, while file.appUrl offered a public-facing URL. Both have been removed in favor of a unified approach that better handles security concerns.

You’ll typically encounter these deprecation warnings in your development console when running your application after upgrading UploadThing. The warnings usually look something like:

Warning: file.url is deprecated and will be removed in a future version. Please use file.fileUrl instead.
Warning: file.appUrl is deprecated and will be removed in a future version. Please use file.fileUrl instead.

The key insight here is that both deprecated properties have been consolidated into a single, more secure replacement. This simplification makes the API more intuitive while improving security posture.

Migration Guide: Upgrading from UploadThing 7.7.4

Upgrading your UploadThing code from version 7.7.4 to a newer version requires systematic updates to address the deprecation warnings. Here’s a step-by-step approach to ensure a smooth transition:

Step 1: Update Your Dependencies

First, ensure you’re using a recent version of the UploadThing package:

npm install uploadthing@latest
# or
yarn add uploadthing@latest

Check your package.json to confirm you’ve upgraded from the older 7.7.4 version to at least version 8.0.0 or higher.

Step 2: Identify All Usage of Deprecated Properties

Search your codebase for any instances of file.url and file.appUrl. These might appear in:

• File upload handlers
• Database storage functions
• Frontend components
• API responses

Step 3: Replace with New Properties

The new unified property is file.fileUrl. Replace all instances:

// Before (deprecated)
const fileUrl = file.url;
const publicUrl = file.appUrl;

// After (new approach)
const fileUrl = file.fileUrl;

Step 4: Update Framework-Specific Code

If you’re using framework adapters, you’ll need to update those as well. For example, in React components:

// Before
const { url, appUrl } = uploadedFile;

// After
const { fileUrl } = uploadedFile;

Step 5: Test Your Implementation

Thoroughly test your updated code to ensure:

• File uploads still work correctly
• URLs are accessible as expected
• No functionality has been broken

Step 6: Clean Up Old References

Once you’ve confirmed everything works, remove any remaining references to the deprecated properties and consider adding type definitions if you’re using TypeScript to prevent future regressions.

Updated Code Examples for the New API

Let’s look at practical code examples showing how to update your UploadThing implementation for the new API.

Basic Upload Handler

// Before (deprecated)
import { createUploadthing } from "uploadthing/express";

export const ourFileRouter = createUploadthing()
 .middleware((req) => {
 return { userId: req.body.userId };
 })
 .onUploadComplete(async ({ metadata, file }) => {
 console.log("Upload complete for userId:", metadata.userId);
 console.log("File URL:", file.url); // DEPRECATED
 console.log("App URL:", file.appUrl); // DEPRECATED
 
 return {
 fileUrl: file.url, // DEPRECATED
 name: file.name,
 };
 });

// After (new API)
import { createUploadthing } from "uploadthing/express";

export const ourFileRouter = createUploadthing()
 .middleware((req) => {
 return { userId: req.body.userId };
 })
 .onUploadComplete(async ({ metadata, file }) => {
 console.log("Upload complete for userId:", metadata.userId);
 console.log("File URL:", file.fileUrl); // NEW
 
 return {
 fileUrl: file.fileUrl, // NEW
 name: file.name,
 };
 });

React Component Example

// Before (deprecated)
import { UploadButton } from "@uploadthing/react";

function FileUploader() {
 return (
 <UploadButton
 endpoint="imageUploader"
 onClientUploadComplete={(res) => {
 console.log("Upload complete:", res);
 const fileUrl = res[0].url; // DEPRECATED
 const appUrl = res[0].appUrl; // DEPRECATED
 }}
 />
 );
}

// After (new API)
import { UploadButton } from "@uploadthing/react";

function FileUploader() {
 return (
 <UploadButton
 endpoint="imageUploader"
 onClientUploadComplete={(res) => {
 console.log("Upload complete:", res);
 const fileUrl = res[0].fileUrl; // NEW
 }}
 />
 );
}

Database Integration

// Before (deprecated)
async function saveFileToDatabase(file) {
 await prisma.file.create({
 data: {
 name: file.name,
 url: file.url, // DEPRECATED
 appUrl: file.appUrl, // DEPRECATED
 size: file.size,
 type: file.type,
 },
 });
}

// After (new API)
async function saveFileToDatabase(file) {
 await prisma.file.create({
 data: {
 name: file.name,
 url: file.fileUrl, // NEW
 size: file.size,
 type: file.type,
 },
 });
}

Multiple File Handling

// Before (deprecated)
async function handleMultipleUploads(files) {
 const fileData = files.map(file => ({
 name: file.name,
 url: file.url, // DEPRECATED
 appUrl: file.appUrl, // DEPRECATED
 size: file.size,
 }));
 
 return fileData;
}

// After (new API)
async function handleMultipleUploads(files) {
 const fileData = files.map(file => ({
 name: file.name,
 url: file.fileUrl, // NEW
 size: file.size,
 }));
 
 return fileData;
}

These examples demonstrate the straightforward nature of the migration. The key change is simply replacing the deprecated properties with the new fileUrl property across your codebase.

Best Practices for File URL Handling in UploadThing

After updating your code to use the new API, follow these best practices to ensure optimal file URL handling:

1. Use Environment-Specific URL Handling

Different environments (development, staging, production) may require different URL handling approaches. The new UploadThing API provides better built-in support for this:

// Environment-aware URL handling
const getFileUrl = (file) => {
 if (process.env.NODE_ENV === 'production') {
 return file.fileUrl; // Production URL
 } else {
 // Development URL handling
 return file.fileUrl.replace('https://', 'http://');
 }
};

2. Implement Proper Access Control

Just because files are uploaded doesn’t mean they should be publicly accessible by default. Implement proper access controls:

// Access control example
function canAccessFile(file, user) {
 // Check if user has permission to access this file
 return file.userId === user.id || user.role === 'admin';
}

3. Cache File URLs

For performance, consider caching frequently accessed file URLs:

// Simple URL caching
const urlCache = new Map();

function getCachedFileUrl(file) {
 if (urlCache.has(file.id)) {
 return urlCache.get(file.id);
 }
 
 const url = file.fileUrl;
 urlCache.set(file.id, url);
 return url;
}

4. Handle File URL Expiration

Some file services implement expiration for URLs. Handle this gracefully:

// Handle expired URLs
async function getFileUrlWithRetry(file, maxRetries = 3) {
 try {
 return file.fileUrl;
 } catch (error) {
 if (maxRetries > 0 && error.message.includes('expired')) {
 // Refresh the URL and try again
 const refreshedFile = await refreshFileUrl(file.id);
 return getFileUrlWithRetry(refreshedFile, maxRetries - 1);
 }
 throw error;
 }
}

5. Validate File URLs Before Use

Always validate file URLs before using them in your application:

// URL validation
function isValidFileUrl(url) {
 try {
 new URL(url);
 return url.includes('uploadthing.com'); // Ensure it's from UploadThing
 } catch {
 return false;
 }
}

6. Use Framework-Specific Optimizations

UploadThing provides framework-specific adapters that take advantage of the new API. For example, in Next.js:

// Next.js optimized file handling
import { createUploadthing } from "uploadthing/next";
import { createRouteHandler } from "uploadthing/next";

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

7. Monitor for Future Deprecations

Stay informed about API changes by regularly checking the UploadThing documentation for any new deprecation warnings or upcoming changes.

Sources

1. UploadThing Documentation — Official API reference for deprecated properties and migration guides: https://docs.uploadthing.com
2. UploadThing React API — React-specific documentation for file URL handling and component updates: https://docs.uploadthing.com/api-reference/react
3. UploadThing Service Overview — File upload service documentation and best practices: https://uploadthing.com

Conclusion

Updating your UploadThing API code to address deprecation warnings for file.url and file.appUrl is a straightforward process that involves replacing these deprecated properties with the new file.fileUrl property. This migration, while requiring careful code review, actually improves your application’s security and consistency by providing a unified approach to file URL handling.

The key steps include identifying all instances of the deprecated properties in your codebase, systematically replacing them with the new fileUrl property, and thoroughly testing your implementation to ensure all functionality remains intact. The examples provided demonstrate that this migration is primarily a search-and-replace operation with minimal impact on your application’s logic.

By following the best practices outlined—such as implementing proper access controls, caching file URLs, and handling environment-specific requirements—you can ensure your file upload system remains robust and secure after the migration. Remember to stay updated with UploadThing’s documentation for any future API changes, as proactive maintenance will save you from more complex migrations down the line.

Ultimately, this deprecation update represents an opportunity to improve your codebase while maintaining compatibility with the latest UploadThing API features and security enhancements.