Plugins
A plugin is a product feature in one folder, plugins/<name>/. It is plugged into core: core
mounts it and hands it scoped services. A plugin never imports core’s code, and core never imports
a plugin by name.
The manifest
Section titled “The manifest”plugin.yaml is the contract between a plugin and core. Codegen validates it before every dev, build
and test run.
| Section | Declares |
|---|---|
id, name, version, owner, dataClass, pii |
Identity, ownership, what personal data it holds |
platform |
The SDK and UI kit versions it is built for |
schema, server |
Its database schema, and its Nest module |
surfaces |
Its screens: web, desktop, mobile, admin, with navigation entries |
permissions |
Its permissions and which roles get them by default |
navigation.routes |
Deep links by route id (screens, notifications and other plugins open them) |
events |
Live events it publishes, with permission and payload schema |
notifications |
Notification types: channels, templates, resolver, destination route |
workers |
Workflows, activities and schedules |
configuration, secrets |
Settings an administrator changes, secrets it needs |
contracts |
Contracts it provides to other plugins, and the ones it uses |
depends |
Plugins it requires (or can use when present) |
Registration: build, deploy, start-up
Section titled “Registration: build, deploy, start-up”A plugin is registered in three steps. There is no adding a plugin to a running instance.
| When | What happens |
|---|---|
| Build — codegen, before every dev, build and test | Reads the instance file, validates every manifest and the composition (dependencies present, versions compatible, one provider per contract), and writes the git-ignored registries — API, workers, user app, App Admin, phone — with static imports of the selected plugins only |
| Deploy — the migration runner | Creates each selected plugin’s schema, database role and permissions, and runs its migrations |
| Start-up — API and worker processes | Core checks every route has a permission or @Public(), mounts each plugin module at /api/v1/plugins/<id>, injects its scoped services, registers contracts; workers register workflows and create schedules |
Adding or removing a plugin is a change to the instance file, a build and a deploy.
Scoped services
Section titled “Scoped services”Core adds PluginSdkModule.forPlugin(plugin) to every plugin module. Each service it provides is
bound to that plugin: PluginDb connects as af_<name> with the plugin’s schema on the search path;
PluginEvents can publish only declared events; PluginAudit prefixes actions with the plugin id;
PluginFiles writes only under the plugin’s prefix. A plugin that tries to provide one of these
itself is refused at start-up.
What a build contains
Section titled “What a build contains”Only the plugins the instance file selects.
- Backend image: compiled from the generated registry, so only selected plugins’ server code is compiled; only their npm dependencies are installed.
- User app, App Admin, desktop: Vite bundles only what the registry imports.
- Phone: Metro, the same way.
An instance’s plugins/ folder holds the plugins it was given; each build compiles only those its
instance file selects.
Boundaries a plugin cannot cross
Section titled “Boundaries a plugin cannot cross”- Another plugin’s or core’s tables — its database role cannot see them.
- Another plugin’s code — lint allows only
@antfabric/*libraries and contracts packages. - A route without
@Permissions(...)or@Public(), or with a permission it did not declare. - Core’s own services — it may not provide them.
- An event, notification type, workflow or contract it did not declare.
Plugins in their own repositories
Section titled “Plugins in their own repositories”Product plugins live in their own repositories under antfabric/antfabric-v2/plugins/ (Chat,
Sales, …); core ships only Example (the UI kit, AntFabric UI, is part of core). A plugin is developed and tested inside a
core instance (pnpm antfabric create, then plugin clone) and comes into an organisation’s
instance as a released version. Every plugin is written to stand alone: SDK imports only, its own
package, tests, migrations and README. See Plugin repositories.