Migrate from Uploadcare to Transloadit

Uploadcare combines uploads, CDN delivery, file groups, and URL operations. Transloadit separates these concerns into upload/import Robots, processing Robots, export Robots, and optional CDN delivery. Inventory the operations you use and map supported processing tasks to Steps in a Transloadit Template; this is not a one-to-one replacement for every Uploadcare feature.

Migration map

Use Step dependencies to route files between processing tasks, not to replace persistent file-group records. Sign Smart CDN URLs on your backend and use a separate compatible Template for on-demand delivery.

Replace the upload widget

For browser uploads, use Uppy with the Transloadit Plugin. Uppy gives you a file picker, drag-and-drop UI, resumable uploads, remote sources, and direct Transloadit integration.

A typical Uploadcare flow where users upload an image and receive transformed CDN URLs becomes:

1. The browser uploads through Uppy and references a saved Transloadit Template.
2. The Template creates all variants your app needs.
3. Transloadit notifies your backend with the result URLs.
4. Your backend stores those URLs in your database.

Configure a notify_url in the signed Assembly request and verify incoming notification signatures. For browser-side completion, enable Uppy’s waitForEncoding; the default only waits for the upload.

Example Template

This Template receives an image upload, creates a square WebP avatar, optimizes both the original and the avatar, and stores the optimized files on S3. Optimization has no format parameter and, with progressive left disabled as here, returns the original if the optimized file is larger. Enabling progressive allows an optimization result to be retained even if it is larger:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "avatar": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 512,
      "height": 512,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized_original": {
      "use": ":original",
      "robot": "/image/optimize",
      "result": true
    },
    "optimized_avatar": {
      "use": "avatar",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": ["optimized_original", "optimized_avatar"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "uploads/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Set up Third-party Credentials for S3 and configure your CDN to serve the bucket root with read access. url_prefix does not create a CDN or grant access. acl: "bucket-default" sends no object ACL; configure access through your bucket policy and CDN origin access. After ASSEMBLY_COMPLETED, read the original from results.optimized_original and the avatar from results.optimized_avatar. Persist only entries with is_temp_url: false: export updates the producing Step’s URLs. Temporary Transloadit URLs expire after 24 hours; see saving conversion results.

Import existing Uploadcare files

If you already have Uploadcare CDN URLs in your database, import them with 🤖/http/import:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.uploadcare_url}"
    },
    "preview": {
      "use": "imported",
      "robot": "/file/preview",
      "result": true
    },
    "exported": {
      "use": ["imported", "preview"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "uploadcare-import/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

The preview Step uses 🤖/file/preview (beta); it may return a generic file-type icon when a content thumbnail is unavailable. Select authorized uploadcare_url values on your backend. Importing a transformed CDN URL copies that rendition, not necessarily the original. You can backfill only referenced files or pass an array of authorized URLs to /http/import for a bounded batch. Keep an old-ID-to-new-location mapping and verify delivery access and output quality before switching reads. This import Template returns exported files under results.imported and results.preview. Private S3 objects need an authorized download or your configured CDN.

Checklist

1. Replace Uploadcare widget usage with Uppy and the Transloadit Plugin.
2. Map the CDN operations you use to supported Template Steps.
3. Export durable results to your storage provider.
4. Save the exported storage URLs from Assembly Notifications.
5. Backfill existing Uploadcare CDN URLs with /http/import.
6. Keep old URLs as a fallback until all important assets have Transloadit results.