UploadingFile UploaderPlugin API

Runtime API

These APIs are available on pluginApi inside setup and inside activity render functions.

pluginApi.config

Read and react to config values at runtime.

config.get

Returns the current value of any config option, including custom ones registered by your plugin.

1const apiKey = pluginApi.config.get('myApiKey');
2const pubkey = pluginApi.config.get('pubkey');

config.subscribe

Calls a callback immediately with the current value and again whenever that config value changes. Returns an unsubscribe function. Subscriptions created during setup are cleaned up automatically when the plugin is unregistered. Subscriptions created inside an activity’s render function should be unsubscribed in that activity’s cleanup function.

1// Inside setup - cleaned up automatically when the plugin is unregistered
2pluginApi.config.subscribe('myApiKey', (value) => {
3  console.log('myApiKey changed:', value);
4});

Inside an activity’s render function, tie the subscription to that mount and unsubscribe in the returned cleanup function:

1pluginApi.registry.registerActivity({
2  id: 'my-activity',
3  render(host) {
4    const el = document.createElement('my-activity-element');
5    el.apiKey = pluginApi.config.get('myApiKey');
6
7    const unsubscribe = pluginApi.config.subscribe('myApiKey', (value) => {
8      el.apiKey = value;
9    });
10
11    host.replaceChildren(el);
12
13    return () => {
14      unsubscribe();
15      host.replaceChildren();
16    };
17  },
18});

pluginApi.activity

Access the parameters passed to the currently active activity via setCurrentActivity.

activity.getParams

Returns the current activity parameters synchronously. Useful for reading params once at setup time or at the start of an activity render.

1const params = pluginApi.activity.getParams();
2// { fileId: 'abc123', ... }

activity.subscribeToParams

Subscribes to parameter changes. The callback fires immediately with the current params, then on every subsequent update. Returns an unsubscribe function.

1pluginApi.activity.subscribeToParams((params) => {
2  console.log('Activity params:', params);
3});

The render function receives params as its second argument for the initial mount, but if your activity can be re-activated with new params while already mounted, use subscribeToParams inside render to react to those updates:

1pluginApi.registry.registerActivity({
2  id: 'my-activity',
3  render(host, initialParams) {
4    const el = document.createElement('my-activity-element');
5    el.fileId = initialParams.fileId;
6
7    // React to subsequent param changes without unmounting
8    const unsub = pluginApi.activity.subscribeToParams((params) => {
9      el.fileId = params.fileId;
10    });
11
12    host.replaceChildren(el);
13
14    return () => {
15      unsub();
16      host.replaceChildren();
17    };
18  },
19});

pluginApi.files

Mutate file entries in the upload collection.

files.update

Updates mutable properties of a file entry by its internalId.

1// Client-side edit: replace the file blob
2pluginApi.files.update(fileEntry.internalId, {
3  file: transformedBlob,
4  mimeType: 'image/webp',
5});
6
7// Server-side edit: update the CDN URL instead
8pluginApi.files.update(fileEntry.internalId, {
9  cdnUrl: 'https://ucarecdn.com/uuid/-/preview/800x600/',
10});
PropertyTypeDescription
fileFile | BlobReplace the file data.
cdnUrlstring | nullOverride the CDN URL.
cdnUrlModifiersstring | nullOverride CDN URL modifiers (transformation directives).
mimeTypestring | nullOverride the MIME type.