Plugins
Plugins are self-describing capabilities of a known type, such as converters that read file types and document processes for the AI Document. Write your own, and add them from a module or a plugins folder.
A module customizes your UAG deployment: it is the one place you wire the server — your project template, form actions, MCP tools, hooks, interface overrides, and which plugins to load. A plugin is one capability of a known type — "convert Word documents to PDF", "extract a document's exact text" — that describes itself, so operators can enable it and form builders can select and configure it. Modules can bring plugins; plugins never change how the server itself works.
Plugins are trusted code. A plugin runs in the UAG process, with the UAG's secrets: engine API keys, the project or admin key, the JWT secret. Adding a plugin, or mounting a plugins folder, is installing software. Only add plugins you trust.
Adding plugins
From a module, list them in plugins (and any plugin types the module defines in pluginTypes). Modules add to one registry in the order they are used; their lists are never merged with each other.
module.exports = {
config: { /* ... */ },
plugins: [require('./my-converter')]
};From a plugins file: an ES module (.mjs) or CommonJS file whose default export (or plugins export) is a plugin, a list of plugins, or nested lists; or a list mixing modules and plugins, each module used in turn. Document plugins need the AI Document module, which defines their type. The uag command and the formio/uag image load the plugins folder /app/plugins when it exists, or what UAG_PLUGINS names (UAG_PLUGINS=off loads none):
- a file: that file;
- a folder with an
index.mjs: that file; - any other folder: the
index.mjsof each folder in it, in name order, one per add-on (node_modulesand folders whose name starts with.are skipped).
In your own server, usePluginFiles(server) does the same (see Node.js API). Relative imports in a file resolve from the file, and bare imports from its folder's own node_modules, then upward.
// my-plugins/index.mjs: the AI Document module and the official plugins, plus your own
import { UAGDocument } from '@formio/uag-extras/modules/ai-document';
import Extract from '@formio/uag-extras/documents/extract';
import Analyze from '@formio/uag-extras/documents/analyze';
import Translate from '@formio/uag-extras/documents/translate';
import OfficeText from '@formio/uag-extras/converters/office-text';
import myConverter from './my-converter.mjs';
export default [UAGDocument, Extract, Analyze, Translate, OfficeText, myConverter];These plugins come from @formio/uag-extras, the package of UAG extras (modules, actions, MCP tools, engine types, document plugins and converters) from Form.io and the community: npm install @formio/uag-extras@^2 in the plugins folder (it needs @formio/uag 2.0.0 or later and Node.js 24 or later). See @formio/uag-extras on npm. Each extra is its own import, @formio/uag-extras/<kind>/<name>: its default export is a module for server.use(), and its plugin is a named export, for plugins files. In Docker, the formio/uag-documents add-on brings the AI Document module and these plugins, so your own folder beside it lists only yours (see Add-ons). A plugin that needs system packages (an OCR engine) needs them in the UAG's container: build an image FROM formio/uag:<version> that adds them with apk add, and mount or copy the plugins there.
Add-ons
In Docker, each set of plugins is a folder of its own under /app/plugins, with its own index.mjs and node_modules. An add-on is an image that holds such a folder: run once, it copies the folder into the volume mounted at /out, replacing what the volume held, and exits. The UAG mounts each add-on's volume in its own folder, and a folder of your own beside them:
services:
uag-documents:
image: formio/uag-documents:2
volumes:
- uag-documents:/out
uag-crm: # an example: any add-on is run the same way
image: example/uag-crm:1
volumes:
- uag-crm:/out
formio-uag:
image: formio/uag
depends_on:
uag-documents:
condition: service_completed_successfully
restart: true
uag-crm:
condition: service_completed_successfully
restart: true
volumes:
- uag-documents:/app/plugins/documents:ro
- uag-crm:/app/plugins/crm:ro
- ./my-plugins:/app/plugins/my-plugins:ro
volumes:
uag-documents:
uag-crm:The UAG loads /app/plugins/crm/index.mjs, /app/plugins/documents/index.mjs and /app/plugins/my-plugins/index.mjs, in that order, each as it loads one plugins file, and logs each. They merge as modules do:
- A plugin may use a plugin type another folder's module defines: your
documentplugins need the AI Document module, which theuag-documentsadd-on brings, so your folder need not list it. - A module two folders bring, of the same
nameandversion, is used once. Two versions of it stop startup:Two versions of the module ai-document are used: … Use one. - Two folders that register the same plugin (
type:name), plugin type, form route or component type stop startup, naming both files:Plugin document:translate is registered twice: by /app/plugins/documents/index.mjs… and by /app/plugins/my-plugins/index.mjs. PLUGINS_DISABLEDandMODULES_DISABLEDleave out what you do not want from any of them.
restart: true restarts the UAG when Compose runs a newer add-on, so docker compose pull and docker compose up -d upgrade it. To remove an add-on, delete its service, its depends_on entry, its mount and its volume. With docker run, run each add-on into its volume first (docker run --rm -v uag-documents:/out formio/uag-documents:2), then mount the volumes (-v uag-documents:/app/plugins/documents:ro). On Kubernetes, each add-on is an initContainer writing to its own emptyDir at /out, mounted at /app/plugins/<name> in the UAG's container. Loading folders under /app/plugins needs formio/uag 2.0.0 or later.
To ship your own plugins folder the same way, build an add-on of your own:
FROM alpine:3
COPY my-plugins /plugins
CMD ["sh", "-c", "find /out -mindepth 1 -delete && cp -a /plugins/. /out/"]Every add-on runs in the UAG process with its secrets: add only add-ons you trust (see Security).
Settings and switching plugins off
A plugin's operator settings resolve, first match wins, from config.plugins.settings[type][name][key], then the first set environment variable the setting names, then its default. A required setting with no value stops startup, naming the plugin, the setting and its variables; secret values appear as *** in every message.
config.plugins.disabled (or PLUGINS_DISABLED, comma-separated) lists plugins not to load, as type:name: PLUGINS_DISABLED=converter:office-text.
Startup
Startup stops, naming the plugin and where it came from, for a plugin of an unknown type, an unsupported contract version, a type's validation problems, an editForm its type does not allow, or two plugins with the same type:name. A plugin that is valid but cannot run here (its available() returns false or a reason) is disabled with the reason logged: [plugins] converter:ocr-text is disabled: tesseract was not found.
The plugin contract
Every plugin is a plain object, validated by its shape (no base class, so a plugin built against another copy of a package still registers):
| Field | Meaning |
|---|---|
type |
The plugin type, such as converter. |
name |
/^[a-z][a-z0-9-]{0,62}$/, unique within the type. |
title, description |
What people see. |
version |
The plugin's own version (semver). |
apiVersion |
The version of its type's contract it was built for. |
settings |
Operator settings: { key: { env, required, secret, default, type, description } }. |
editForm |
Per-use settings form, when its type has one. |
available(context) |
true, or the reason it cannot run here. |
setup(context), close() |
Start and stop. context holds the resolved settings, the server module and a log prefixed [plugin type:name]. |
definePlugin(plugin) (exported by @formio/uag) validates the base shape and returns the plugin, for authoring with types.
GET {project}/plugins (any authenticated caller of the project, ?type= to filter) returns the installed plugins' public description: never functions or settings values.
What experimental means
The converter and document types are experimental in 2.0: their contracts may change in a 2.x minor release, with the change in the changelog. The base contract above is stable. The UAG logs one notice at startup for each plugin of an experimental type it did not register itself, and GET {project}/plugins shows each plugin's stability. The example converter below is the reference: a change that breaks it is a contract change. Both types become stable after a minor release in which neither contract changed.
Plugin types in this release
| Type | What a plugin of it does | Stability |
|---|---|---|
converter |
Turns an uploaded file into a PDF or text, which is what AI engines read. Chosen automatically by file type. | Experimental |
document |
Turns files and a form designer's instructions into content for the AI Document component. Chosen per component in the form builder. | Experimental |
engine, tool, action |
Listed only: engines, MCP tools and form actions keep loading as before, and appear in GET {project}/plugins. |
Stable |
module |
Listed only: each module in use that declares an apiVersion, as module:<name>. |
Experimental |
The UAG registers the listed-only types itself: a plugin of one of them in a module's plugins or in a plugins file stops startup.
Your first document plugin
A document plugin is one JavaScript file: a plain object with a few fields and an async process(). The UAG does the rest: it turns each upload into a PDF or text (through the converters), chooses the engine, streams progress to the form, sanitizes what you return and shows it in the component. This walkthrough builds Translate: the form designer picks a language, and the person filling the form gets their upload back in it.
The formio/uag-documents add-on ships this plugin as @formio/uag-extras/documents/translate (the same code, with more languages). Two plugins cannot share document:translate, so to run your own copy beside the add-on's, give yours another name, or leave the official one out of your plugins file.
1. Write the plugin
// my-plugins/translate.mjs
const LANGUAGES = { es: 'Spanish', fr: 'French', de: 'German', pt: 'Portuguese' };
export default {
type: 'document',
name: 'translate',
title: 'Translate',
description: 'Translates the uploaded documents into the language the form designer picks.',
version: '1.0.0',
apiVersion: 1,
inputs: [['pdf'], ['text']], // a PDF when the engine reads one, else the text
editable: true, // people may correct the translation
output: 'markdown',
// Shown on the component's AI tab once this plugin is picked.
editForm: [{
type: 'select', key: 'language', label: 'Translate into', input: true,
dataSrc: 'values',
data: { values: Object.entries(LANGUAGES).map(([value, label]) => ({ value, label })) },
validate: { required: true }
}],
defaults: { language: 'es' },
// Problems here stop processing with "The AI Document … is misconfigured: …".
validateSettings(settings) {
return LANGUAGES[settings.language] ? [] : ['pick a language to translate into'];
},
async process(ctx) {
const language = LANGUAGES[ctx.settings.language];
ctx.progress(0.1, `Translating into ${language}`);
const answer = await ctx.agent.generate({
system: `Translate the attached documents into ${language}. Keep their headings, lists and numbers. Translate only: add nothing.`,
instructions: ctx.instructions,
attachments: ctx.files.map((file, i) => file.document.pdf
? { kind: 'pdf', data: file.document.pdf, label: `Document ${i + 1}: ${file.name}` }
: { kind: 'text', text: file.document.text ?? '', label: `Document ${i + 1}: ${file.name}` }),
format: 'markdown'
});
if (answer.stopReason === 'max_tokens') {
return { content: answer.text, status: 'flagged', issues: [{ kind: 'truncated', message: 'The translation was cut off.' }] };
}
return { content: answer.text, status: 'ok', issues: [] };
}
};Your code decides what to ask the engine and when a result is ok or flagged. Nothing else is needed: no base class, no build step, and no dependency (wrap it in definePlugin from @formio/uag if you want the shape checked as you write).
2. List it in a plugins file
// my-plugins/index.mjs: the AI Document module, which defines the document type, and your plugin
import { UAGDocument } from '@formio/uag-extras/modules/ai-document';
import translate from './translate.mjs';
export default [UAGDocument, translate];3. Test it without a server
process() only uses what it is given, so a stand-in ctx with a fake agent.generate tests it with no UAG and no engine:
// my-plugins/test/translate.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';
import translate from '../translate.mjs';
test('asks the engine for the chosen language', async () => {
const calls = [];
const ctx = {
settings: { language: 'fr' }, instructions: 'Translate the notice for the tenant.',
files: [{ name: 'notice.txt', document: { text: 'Your rent changes on December 1.' } }],
progress: () => {},
agent: { generate: async (request) => { calls.push(request); return { text: '# Avis', stopReason: 'end_turn' }; } }
};
assert.equal((await translate.process(ctx)).status, 'ok');
assert.match(calls[0].system, /French/);
});node --test test/*.test.mjs4. Load it into the UAG
Name the plugins file with UAG_PLUGINS:
UAG_PLUGINS=./my-plugins/index.mjs npx uagWith Docker, mount the folder beside the formio/uag-documents add-on, in a folder of its own under /app/plugins (see Add-ons):
volumes:
- uag-documents:/app/plugins/documents:ro
- ./my-plugins:/app/plugins/my-plugins:roThe add-on brings the AI Document module and its own document:translate, so beside it, list only your plugin, under another name (name: 'my-translate' in translate.mjs):
// my-plugins/index.mjs, beside the add-on
import translate from './translate.mjs';
export default [translate];At startup the UAG logs each plugins file it loaded, and a notice that document plugins are experimental:
[formio-uag] Plugins and modules loaded from /app/plugins/documents/index.mjs.
[formio-uag] Plugins loaded from /app/plugins/my-plugins/index.mjs.
[plugins] document:my-translate (from /app/plugins/my-plugins/index.mjs) uses the experimental "document" plugin type: …A plugin of the wrong shape stops startup, naming it and the problem (see Startup). GET {project}/plugins lists it once it is installed.
5. Use it in the form builder
Reload the builder (in the developer portal, reload the page: the portal script carries the plugin list it was loaded with). Add an AI Document, open its AI tab and pick Translate under Process: its Translate into setting appears. Write the instructions (every AI Document needs them: "Translate the notice for the tenant"), choose a target field if the translation should land in one, and save.
The UAG reads its plugins once, at startup: restart it after you change one.
When it does not work
| What you see | Why |
|---|---|
Startup stops: no plugin type "document" |
The AI Document module is not in use: add UAGDocument from @formio/uag-extras/modules/ai-document into your plugins file or module. |
Startup stops: Plugin document:translate is registered twice |
Your plugin and @formio/uag-extras/documents/translate (in the add-on, or your own list) share a name: rename yours, or leave the official one out. The message names both files. |
The AI Document "…" is misconfigured: its process "translate" is not installed or not available. |
The UAG serving the form did not load your plugins file: check UAG_PLUGINS or the mount (a folder under /app/plugins, holding index.mjs), and the startup log. |
The AI Document "…" is misconfigured: pick a language to translate into |
Your validateSettings refused the component's settings. |
The AI Document "…" is misconfigured: it has no instructions. |
The component's instructions are empty. |
"notice.docx" is application/vnd.openxmlformats-officedocument.wordprocessingml.document, which no installed converter brings to the "translate" process. |
No converter turns that file type into a PDF or text: add @formio/uag-extras/converters/office-text for Word and Excel (with its peer dependencies, mammoth, node-html-markdown and exceljs). |
| The result is flagged with your issue | Your process() returned status: 'flagged': people see the issues and decide. |
Writing a converter
A converter (apiVersion: 1) turns one file into a PDF or text:
import { definePlugin } from '@formio/uag';
export default definePlugin({
type: 'converter',
name: 'sample-text',
title: 'Sample text',
version: '1.0.0',
apiVersion: 1,
accepts: [{ type: 'application/x-uag-sample', ext: ['.uagsample'] }],
produces: ['text'],
// For formats the UAG's own detection does not know: the type, from the first bytes.
detect: (head) => head.subarray(0, 11).toString() === 'UAGSAMPLE1\n' ? 'application/x-uag-sample' : null,
async convert(input, { to, settings, signal, tmpdir, log }) {
signal.throwIfAborted();
return { text: input.buffer.subarray(11).toString('utf8'), textFormat: 'plain' };
}
});acceptslists canonical MIME types and their extensions;producesispdf,textor both.convertgets the file (buffer,type,name) and{ to, settings, signal, tmpdir, log }, wheresettingsare the converter's operator settings (see Settings and switching plugins off). It returns{ pdf, pages?, warnings? }or{ text, textFormat: 'plain' | 'markdown' | 'csv', pages?: [{ page, text }], warnings? }, and must give the same output for the same input and version.- The UAG runs each call with a temporary directory of its own (removed after), under
limits.timeoutMs(aborted throughsignal, so stop any process you started),limits.concurrencycalls at once, andlimits.maxBytes(defaults: 120000 ms, 2, 25 MB). rank(default 0) decides between converters that can do the same step: a component's pin, thendocuments.prefer, then the highest rank, then the name.
Files are identified from their bytes (the name and the browser's type are hints only), so a converter's detect is how a new format gets its type. The built-in converters are pdf-text (a PDF's text layer, per page), text (text, Markdown, CSV, JSON, HTML as Markdown, XML; UTF-8, UTF-16, and Latin-1 or Windows-1252 for files named as text) and image-pdf (PNG and JPEG as a one-page PDF; a PNG over 50 megapixels is refused before it is decoded; its operator setting maxPixels, config.plugins.settings.converter['image-pdf'].maxPixels or DOCUMENTS_MAX_IMAGE_PIXELS (default 50000000), changes that). A file that converts to no text, such as an image or a scan, is refused with the converter's reason when it is read as text.
The sample converter, examples/converter-sample/ in the @formio/uag-extras source repository, is the starting point, and that repository is where to share one: in a clone of it, npm run new -- converters <name> starts a converter from the sample, with its manifest, README and a test, and a contract test loads the samples into a UAG build.
Writing a document plugin
A document plugin (apiVersion: 1) turns the component's files and the form designer's instructions into content (the walkthrough above builds one step by step):
export default {
type: 'document',
name: 'summary',
title: 'Summary',
version: '1.0.0',
apiVersion: 1,
inputs: [['pdf'], ['text']], // representation sets, in order of preference
editable: true, // may people edit the content?
output: 'markdown',
editForm: [{ type: 'number', key: 'maxWords', label: 'Most words', input: true }],
defaults: {},
async process(ctx) {
const attachments = ctx.files.map((file, i) => file.document.pdf
? { kind: 'pdf', data: file.document.pdf, label: `Document ${i + 1}: ${file.name}` }
: { kind: 'text', text: file.document.text, label: `Document ${i + 1}: ${file.name}` });
const answer = await ctx.agent.generate({ instructions: ctx.instructions, attachments, format: 'markdown' });
return { content: answer.text, status: answer.stopReason === 'max_tokens' ? 'flagged' : 'ok' };
}
};ctx.filesholds one entry per file:name,type,size,sha256,document(pdf,pages,text,textFormat,textPages), therouteit took andoriginal(). When a set has bothpdfandtext, the text is that same PDF's text.ctx.instructionsis Markdown;ctx.settingsthis component's settings (defaultsapplied);ctx.configthe operator settings;ctx.datathe submission data sent (context only: untrusted).ctx.agent.generatecalls the engine the component or the operator chose; call it again to retry with feedback.ctx.progress(fraction, message)reports progress; honourctx.signal.- Return
{ content, status: 'ok' | 'flagged', issues?, summary? }(at most 50 issues of at most 300 characters each). Throw to fail: the message is shown to the person, so never put document text in it. editFormis JSON only; its keys are relative to the plugin's settings.
The UAG sanitizes Markdown content before returning it: raw HTML, unsafe links and images are removed.
Next steps
- AI Document: the component, the process route, and running it.
- Modules: wiring a deployment.