Plugin structure & registration

Plugin structure

A plugin is an object with a stable id and a setup function:

1
import type { UploaderPlugin } from '@uploadcare/file-uploader';
2
3
export const myPlugin: UploaderPlugin = {
4
  id: 'my-plugin',
5
  setup({ pluginApi, uploaderApi }) {
6
    // register everything here
7
  },
8
};

Treat id as the plugin’s identity within a single uploader context. It must be unique for that context.

The setup function receives a single object with the following properties:

setup can be synchronous or async. It can also return a disposer function that runs when the plugin is unregistered.

Registering plugins

Pass plugins to the <uc-config> element via its plugins property:

1
<uc-config id="cfg" ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>
2
<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
3
4
<script type="module">
5
  import { myPlugin } from './my-plugin.js';
6
7
  const cfg = document.querySelector('#cfg');
8
  cfg.plugins = [myPlugin];
9
</script>

Or in a framework (React example):

1
import { FileUploaderRegular } from '@uploadcare/react-uploader';
2
import { myPlugin } from './my-plugin';
3
4
export function Uploader() {
5
  return <FileUploaderRegular pubkey="YOUR_PUBLIC_KEY" plugins={[myPlugin]} />;
6
}

Plugins are initialized in array order. Replacing cfg.plugins causes the uploader to resync the list: removed plugins are disposed, new plugins are set up, and duplicates by id are skipped.

1
cfg.plugins = [...cfg.plugins, newPlugin];

Cleanup and disposal

If setup returns a disposer function, it runs when the plugin is removed from the plugins array or when the uploader is destroyed.

1
const myPlugin: UploaderPlugin = {
2
  id: 'my-plugin',
3
  setup({ pluginApi }) {
4
    const interval = setInterval(poll, 5000);
5
6
    return () => {
7
      clearInterval(interval);
8
    };
9
  },
10
};

Subscriptions created with pluginApi.config.subscribe and pluginApi.activity.subscribeToParams inside setup are cleaned up automatically when the plugin is unregistered. If you create subscriptions inside an activity’s render function, unsubscribe them in the cleanup function returned from render so they do not outlive that activity mount.