initCompanion(options)

The initCompanion function initializes and configures the Uppy Companion middleware, which is essential for enabling users to import files from remote sources like Unsplash, Google Drive, Instagram, or direct URLs. This function is a wrapper around the official @uppy/companion library, tailored for seamless integration within a blocklet environment.

For a practical guide on setting this up, see Integrating Remote Sources (Companion).

How It Works#

Companion acts as a server-side proxy. When a user selects a file from a remote source, the request is sent to your backend's Companion endpoint. Your server then fetches the file from the remote source and streams it back to the user's browser. Once in the browser, the file is treated like a local file and uploaded to your final destination (e.g., the endpoint handled by initLocalStorageServer).

Usage#

To use Companion, initialize it with your configuration options and then attach its handle to an Express router path. The frontend Uploader component must be configured with the same path for its companionUrl prop.

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

const router = express.Router();

// Basic configuration for Companion
const companion = initCompanion({
  // A temporary directory on your server for processing files
  path: '/tmp/uploads',
  express,
  // Provider options with necessary keys and secrets
  providerOptions: {
    unsplash: {
      key: process.env.UNSPLASH_KEY,
      secret: process.env.UNSPLASH_SECRET,
    },
  },
  // The public URL of your blocklet, required by some providers
  uploadUrls: [process.env.APP_URL],
});

// Mount the companion middleware on a specific path
// This path should match the `companionUrl` prop on the frontend
router.use('/companion', companion.handle);

Parameters#

The initCompanion function accepts a single options object with the following properties:

Name	Type	Description
path	string	Required. The absolute path to a temporary directory on the server where files will be stored during processing. This corresponds to the filePath option in Uppy Companion.
express	Function	Required. The Express application instance. This is used to create the necessary sub-app and middleware stack for Companion.
providerOptions	object	Optional. An object containing the configuration for each remote provider you want to enable. Each key is the provider name (e.g., unsplash), and the value is its configuration, like API keys and secrets.
...restProps	any	Any other valid option from the official Uppy Companion options can be passed here. For example, uploadUrls is a common and often required option.

Return Value#

The function returns a companion instance with the following key properties:

Property	Type	Description
handle	Function	An Express middleware that you must mount on a route (e.g., /companion). This handle contains all the logic for processing remote file requests.
setProviderOptions	(options: object) => void	A method that allows you to dynamically update the providerOptions after initialization. This is useful if you need to load API keys from a database or change configurations without restarting the server.

Example: Dynamic Provider Options#

You can change the provider options at runtime, which is useful for multi-tenant applications or when secrets are loaded asynchronously.

// Initialize companion without provider options initially
const companion = initCompanion({
  path: '/tmp/uploads',
  express,
});

// Later, perhaps after fetching secrets from a database
async function updateCompanionConfig() {
  const secrets = await getSecretsFromDb();
  companion.setProviderOptions({
    unsplash: {
      key: secrets.unsplashKey,
      secret: secrets.unsplashSecret,
    },
  });
}

Additional Features#

• Status Code Rewriting: For security and better error handling, if a remote provider returns an error with a status code of 500 or higher, this middleware automatically rewrites it to 400 Bad Request. This prevents potential server error details from leaking to the client.

With Companion set up, your uploader is now capable of handling files from a wide variety of sources. You might also need to serve static files from your blocklet or other blocklets.