Skip to content
AntFabric Corev1.0.0local

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 CI
antfabric-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’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>.

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:

Terminal window
pnpm antfabric create ~/af/dev-core # once, from a core checkout (--ref <tag> once core is tagged)
cd ~/af/dev-core && pnpm dev:setup
pnpm antfabric plugin clone git@git.geekyants.com:antfabric/antfabric-v2/plugins/chat.git
pnpm --filter backend db:migrate
pnpm dev

plugin 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:

Terminal window
pnpm antfabric plugin add af.chat@1.0.0 --contracts # @antfabric-contracts/chat, without Chat
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.

  1. Raise version in plugin.yaml and package.json (and the contracts’ version if they changed).
  2. Tag v<version> and push the tag.
  3. CI checks the plugin against CORE_REF, packs it and uploads two files to the repository’s GitLab package registry: <id>-<version>.tgz and <id>-contracts-<contracts version>.tgz. No CI runner is attached yet, so today these jobs do not run: pack with pnpm antfabric plugin pack <name> and share the file, or clone the repository.
Terminal window
export GITLAB_TOKEN=… # a personal or deploy token with read_package_registry
pnpm antfabric plugin add af.chat@0.1.0
pnpm antfabric plugin add af.sales@0.1.0
pnpm --filter backend db:migrate

add 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.

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.