Integrating Remote Sources (Companion)

To allow users to import files from external sources like direct URLs or services like Unsplash, you need to set up Uppy's Companion service on your backend. The @blocklet/uploader-server package provides a convenient initCompanion function that simplifies this process.

Companion acts as a server-side proxy. It fetches files from remote providers on behalf of the user and then streams them to the frontend uploader component, which then proceeds with the normal upload process. While basic file uploads can be handled without a custom backend, enabling remote sources requires setting up the @blocklet/uploader-server package.

How It Works

The following diagram illustrates the data flow when a user imports a file from a remote source:

Step 1: Configure the Backend Middleware

First, you need to initialize and mount the Companion middleware in your blocklet's backend Express server. This involves calling initCompanion and adding it to your router.

Server-side Companion Setup

import express from 'express';
import { initCompanion } from '@blocklet/uploader-server';

const router = express.Router();

// Companion middleware for remote sources
const companion = initCompanion({
  path: env.uploadDir, // A temporary directory for file processing
  express,
  providerOptions: {
    // Configure providers here, e.g., Unsplash
    unsplash: {
      key: process.env.UNSPLASH_KEY,
      secret: process.env.UNSPLASH_SECRET,
    },
  },
  uploadUrls: [env.appUrl], // Your blocklet's public URL
});

// Mount the companion handler on a specific route
router.use('/companion', companion.handle);

initCompanion Options

Step 2: Configure the Frontend Component

After setting up the backend, you need to configure the frontend <Uploader /> component to communicate with your Companion instance. You do this by specifying the route in the apiPathProps prop and enabling the desired plugins.

Uploader Component with Companion

import { Uploader } from '@blocklet/uploader';

function MyUploaderComponent() {
  return (
    <Uploader
      popup
      apiPathProps={{
        // This path must match the backend route
        companion: '/api/companion',
        // The uploader path for the final upload
        uploader: '/api/uploads',
      }}
      plugins={[
        'Url', // Enables importing from a direct URL
        'Unsplash', // Enables importing from Unsplash
        'Webcam',
      ]}
    />
  );
}

With both the backend middleware and frontend component configured, the Uploader's dashboard will now display tabs for "Link" (URL) and "Unsplash", allowing users to import files directly from those sources.

Now that you can handle uploads from both local and remote sources, you might want to extend the uploader's functionality even further. Learn how to add your own custom tabs to the Uploader interface in the next guide.