Devkit: create, pack and add plugins
The idea
Section titled “The idea”antfabric create my-app a core instance of your own, ready to runcd my-appantfabric plugin new crm a plugin in plugins/crm, selected in the instance filepnpm dev develop it inside core, with everything runningantfabric plugin pack crm dist/plugins/com.acme.crm-0.1.0.tgz, checked and versioned
(another instance)antfabric plugin add com.acme.crm-0.1.0.tgz unpacked into plugins/, selected, codegen runThe step-by-step path for a plugin developer (set up, add plugins, daily commands) is Set up and add plugins.
Getting the command
Section titled “Getting the command”Inside a core instance it is a root script:
pnpm antfabric <command>To use it anywhere (needed for create, which runs outside an instance), link it once from a core
checkout:
pnpm --dir tools link --global # puts `antfabric` on your PATHCommands
Section titled “Commands”| Command | Does |
|---|---|
antfabric create <dir> [--ref <tag>] |
Clones core’s main (or the branch or tag in --ref) into <dir> with a fresh git history, selects only the Example plugin (core ships no product plugins; the UI kit is part of core), records the core commit and a fingerprint of every core file in instances/core.json, commits core as cloned, and installs. --repo <url> picks another core repository; --setup also runs pnpm dev:setup |
antfabric plugin new <name> |
Creates plugins/<name> from the generator, selects it in the instance file and links it, so pnpm dev runs it |
antfabric plugin pack <name> |
Checks the plugin, then writes dist/plugins/<id>-<version>.tgz |
antfabric plugin add <file.tgz | url | id@version> [--contracts] [--force] |
Unpacks a packed plugin into plugins/, selects it in the instance file, installs and runs codegen. <id>@<version> downloads a release from the plugin repository’s GitLab package registry (GITLAB_TOKEN); --contracts takes its contract package only |
antfabric plugin clone <git-url> [folder] |
Clones a plugin’s own repository into plugins/<folder> (a real folder with its own .git, named from the plugin’s id: af.ai-gateway → ai_gateway) and selects it. See Plugin repositories |
antfabric plugin select <folder|id> |
Selects a plugin folder already in plugins/, installs and runs codegen |
antfabric plugin remove <id> [--delete] |
Takes a plugin out of the instance file; --delete also removes its folder |
antfabric plugin run <id> <task> [args…] |
Runs a task the plugin declares in plugin.yaml tasks in its own process (exit 0 done, 1 failed, 2 unknown task); see the plugin lifecycle docs |
antfabric check |
Reports core files that were modified, added or removed in this instance (see below) |
antfabric update [--ref <branch or tag>] |
Moves this instance to a newer core (core’s main, or the branch or tag it was created with, or --ref), keeping your plugins, instances/ and .env files (see Updating core). --no-install skips the install and API spec |
The instance file is instances/local.yaml, or AF_INSTANCE.
Core stays untouched
Section titled “Core stays untouched”A plugin developer never edits core: everything a plugin needs is in plugins/<name>/, and an
instance that receives the plugin has the real core, not your edits.
createfingerprints every core file (instances/core.json) and makes the first commit core as cloned, without hooks.antfabric checklists core files that are modified, added or removed:
✕ core changed in this instance; plugins live only in plugins/<name>/: modified libs/sdk-server/src/index.ts added apps/web/src/hack.tsPut them back as core 98c1fee has them: git checkout -- <file> (new files: delete them).plugin packruns it first and will not pack while core is changed.- The pre-commit hook runs it in every instance, so a core change is not committed either.
Yours to change: your plugin folders, instances/, plugins added from a package (they carry
antfabric-plugin.json), and files core’s commands rewrite (pnpm-lock.yaml,
apps/backend/openapi.json, libs/api-client/src/schema.ts). Removing a core plugin with
plugin remove --delete is allowed. In core itself (no instances/core.json) the check does
nothing.
It is a guardrail, not a lock; compiled core packages, later, take core out of the instance.
Updating core
Section titled “Updating core”Core changes often. Bring an instance up to date in place; your apps, data and plugins stay:
pnpm antfabric update # core's main, or the ref the instance was created withpnpm --filter backend db:migrate # core's new migrations# restart pnpm dev, then commit:git add -A && git commit -m "chore: AntFabric core <commit>"What it does:
- Fetches core (
--reffor a branch or tag;--repofor another repository). - Refuses if core files were edited here, as
antfabric checkreports them, unless the edit is exactly what the new core has. Nothing of yours is overwritten. - Replaces changed core files, adds new ones and deletes the ones core dropped. Plugins you
cloned, added or created, plugins you removed,
instances/and.envfiles are left alone. - Records the new commit and fingerprint in
instances/core.json, runspnpm install(the lock file keeps your plugins’ dependencies) andpnpm api:spec(the API spec with your plugins).
✓ core 57bc9ab → 8182904: 24 changed, 0 added, 0 removed (plugins, instances/ and .env untouched)Commit before updating, so git diff shows what core changed and git checkout . undoes it. An
instance created before update existed runs it once from a core checkout, from the instance
folder: node <core>/tools/scripts/antfabric.mts update; after that, pnpm antfabric update.
What pack checks
Section titled “What pack checks”- Core is unchanged (
antfabric check). - The manifest is valid (the same checks codegen runs) and every file it names exists.
plugin.yaml’sversionequals the plugin’spackage.jsonversion.- The plugin type-checks and lints (its imports stay within
@antfabric/*and other plugins’ contracts), and the API and workers module graphs resolve with it (plugins:check --boot).--skip-checksleaves this step out while you are experimenting.
What is in a packed plugin
Section titled “What is in a packed plugin”An npm-style tarball (package/…), so it can later go to any npm registry:
- the plugin folder:
plugin.yaml, code,db/migrations, config, event schemas, notification templates, README. In a git work tree, that’s exactly the files git tracks plus untracked files it doesn’t ignore, so your.gitignoredecides. Outside git, it’s every file. Either way, never.git,.env*(.env.exampleis kept),.npmrc, key files (*.pem,*.key,*.p12,*.pfx),node_modulesor build output.packprints what it left out; antfabric-plugin.json, written bypack:
{ "format": "source", "formatVersion": 1, "id": "af.sales", "name": "Sales", "version": "0.1.0", "folder": "sales", "platform": { "sdk": "^1.0.0", "ui": "^1.0.0" }, "requires": { "plugins": {}, "contracts": { "chat": "^1.1.0" } }, "packedFrom": { "core": "2e7675f" }, "sha256": "…"}add reads it first: an unknown format or a plugin id that is already installed (without
--force) stops it before anything changes. A missing required plugin is reported by codegen with
the usual message.
Contract packages on their own
Section titled “Contract packages on their own”pack also writes dist/plugins/<id>-contracts-<version>.tgz when the plugin has a contracts/
package: its public types and constants, nothing else.
Use it when your plugin uses another plugin’s contract only for types (or calls it only when that
plugin is present), but your instance doesn’t run that plugin. Your package.json still lists
@antfabric-contracts/<name>, and without the package pnpm install fails
(ERR_PNPM_WORKSPACE_PKG_NOT_FOUND). Install it on its own:
antfabric plugin add com.acme.crm-contracts-1.2.0.tgz # → plugins/crm/contracts, nothing selectedantfabric plugin add com.acme.reports-0.3.0.tgz # your plugin, which uses those typesAdding the full plugin later replaces the contracts-only folder with the plugin’s own copy.
In the production build
Section titled “In the production build”Contract packages are compiled into the backend’s dist/ with the plugins that import them. Codegen
writes apps/backend/tsconfig.build.generated.json with a path entry per contract package. The
build then fails if any compiled file still imports a workspace package by name
(scripts/check-dist-imports.mjs), since the production image doesn’t ship workspace packages.
So a plugin may import values (constants, event names) from contracts, not only types.
After add
Section titled “After add”pnpm --filter backend db:migrate # the plugin's schema, role and migrationspnpm devThe plugin is now an ordinary folder in plugins/: commit it with the instance, or keep the tarball
as the release artifact.
Not in this version
Section titled “Not in this version”- Compiled packages and loading plugins from
node_modules. - A core that runs from packages or an image instead of a clone.
- Running one plugin on its own against a minimal core.