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.

1 const apiKey = pluginApi.config.get('myApiKey');
2 const 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
2 pluginApi.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:

1 pluginApi.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.

1 const 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.

1 pluginApi.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:

1 pluginApi.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
2 pluginApi.files.update(fileEntry.internalId, {
3   file: transformedBlob,
4   mimeType: 'image/webp',
5 });
6 
7 // Server-side edit: update the CDN URL instead
8 pluginApi.files.update(fileEntry.internalId, {
9   cdnUrl: 'https://ucarecdn.com/uuid/-/preview/800x600/',
10 });

Property	Type	Description
`file`	`File \| Blob`	Replace the file data.
`cdnUrl`	`string \| null`	Override the CDN URL.
`cdnUrlModifiers`	`string \| null`	Override CDN URL modifiers (transformation directives).
`mimeType`	`string \| null`	Override the MIME type.

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

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

1	pluginApi.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	});

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

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

1	pluginApi.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	});

1	// Client-side edit: replace the file blob
2	pluginApi.files.update(fileEntry.internalId, {
3	file: transformedBlob,
4	mimeType: 'image/webp',
5	});
6
7	// Server-side edit: update the CDN URL instead
8	pluginApi.files.update(fileEntry.internalId, {
9	cdnUrl: 'https://ucarecdn.com/uuid/-/preview/800x600/',
10	});