Plugin repositories
Core (antfabric/antfabric-v2/core-v1) keeps only what every instance needs: core itself, the
devkit, the UI kit (AntFabric UI, libs/ui-kit) and Example, the reference plugin. Every product plugin lives in its own
repository under antfabric/antfabric-v2/plugins,
and instances install released versions of it.
antfabric-v2/core-v1 core (with the UI kit), devkit, af.example (reference)antfabric-v2/plugins/chat af.chat: plugin.yaml at the root, its tests, its CIantfabric-v2/plugins/sales af.sales: uses Chat's contract package<an instance> antfabric create (core main until the first tag) + plugin add <id>@<version>The repository
Section titled “The repository”The repository’s root is the plugin: plugin.yaml, package.json, server/, web/, admin/,
mobile/, contracts/, db/, test/. Start one from core’s template in
tools/templates/plugin-repo/ (CI file, README, .gitignore), with the plugin’s folder from
pnpm antfabric plugin new <name>.
Developing
Section titled “Developing”The whole path, step by step, with every command: Set up and add plugins.
You develop a plugin inside a core instance, where it runs with everything core offers:
pnpm antfabric create ~/af/dev-core # once, from a core checkout (--ref <tag> once core is tagged)cd ~/af/dev-core && pnpm dev:setuppnpm antfabric plugin clone git@git.geekyants.com:antfabric/antfabric-v2/plugins/chat.gitpnpm --filter backend db:migratepnpm devplugin clone puts the repository in plugins/chat as a real folder with its own .git and
selects it. Commit and push from plugins/chat. The folder is named from the plugin’s id, not the
repository: af.ai-gateway from ai-gateway.git lands in plugins/ai_gateway, the name codegen
requires. A folder you cloned yourself is wired in with pnpm antfabric plugin select <folder>
(name it the same way).
A plugin that uses another plugin’s contract installs only that plugin’s contract package:
pnpm antfabric plugin add af.chat@1.0.0 --contracts # @antfabric-contracts/chat, without ChatTesting
Section titled “Testing”| Tests | Where | Run with |
|---|---|---|
| Unit | **/*.spec.ts in the plugin |
pnpm --filter <package> test |
| End to end | test/*.e2e-spec.ts in the plugin |
pnpm --filter backend test:e2e in the instance: core’s suite plus the tests of every selected plugin |
End-to-end tests reach core through one module, @antfabric/backend-testing (createApp,
DBService, SessionService, WorkersModule, ContractRegistry, …), never core’s own paths, so
they keep working while core changes. Core selects only Example (the UI kit is part of core), so its own tests never depend on a product plugin.
Releasing
Section titled “Releasing”- Raise
versioninplugin.yamlandpackage.json(and the contracts’ version if they changed). - Tag
v<version>and push the tag. - CI checks the plugin against
CORE_REF, packs it and uploads two files to the repository’s GitLab package registry:<id>-<version>.tgzand<id>-contracts-<contracts version>.tgz. No CI runner is attached yet, so today these jobs do not run: pack withpnpm antfabric plugin pack <name>and share the file, or clone the repository.
Installing in an instance
Section titled “Installing in an instance”export GITLAB_TOKEN=… # a personal or deploy token with read_package_registrypnpm antfabric plugin add af.chat@0.1.0pnpm antfabric plugin add af.sales@0.1.0pnpm --filter backend db:migrateadd downloads from https://git.geekyants.com/api/v4/projects/antfabric%2Fantfabric-v2%2Fplugins%2F<name>/packages/generic
(ANTFABRIC_PLUGIN_REGISTRY with {name} points it elsewhere), checks the format and checksum,
unpacks into plugins/, selects the plugin and runs codegen. CI uses CI_JOB_TOKEN instead of
GITLAB_TOKEN; the plugin projects must allow the instance’s project in their job token settings.
The plugin’s CI
Section titled “The plugin’s CI”tools/templates/plugin-repo/.gitlab-ci.yml (it runs once a runner is attached to the plugin
projects; none is yet):
| Job | When | Does |
|---|---|---|
check |
Every push | Core at CORE_REF with the plugin in plugins/<repo name>; plugins:check --boot; the plugin’s type check, lint and unit tests; pack |
e2e |
Every push | Core’s e2e suite with the plugin selected, plus the plugin’s own; Postgres, Redis, RustFS, Temporal, Mailpit |
release |
Tag v<version> |
The tag must equal plugin.yaml’s version; pack and upload both files |
CORE_REF is main until core’s first release tag, then that tag. Set PLUGIN_CONTRACTS (e.g.
af.chat@1.0.0) per repository, and add
the plugin’s project to core-v1’s job token allowlist so CI can clone core.