Skip to content
AntFabric Corev1.0.0local

Devkit: create, pack and add plugins

antfabric create my-app a core instance of your own, ready to run
cd my-app
antfabric plugin new crm a plugin in plugins/crm, selected in the instance file
pnpm dev develop it inside core, with everything running
antfabric 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 run

The step-by-step path for a plugin developer (set up, add plugins, daily commands) is Set up and add plugins.

Inside a core instance it is a root script:

Terminal window
pnpm antfabric <command>

To use it anywhere (needed for create, which runs outside an instance), link it once from a core checkout:

Terminal window
pnpm --dir tools link --global # puts `antfabric` on your PATH
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.

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.

  • create fingerprints every core file (instances/core.json) and makes the first commit core as cloned, without hooks.
  • antfabric check lists 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.ts
Put them back as core 98c1fee has them: git checkout -- <file> (new files: delete them).
  • plugin pack runs 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.

Core changes often. Bring an instance up to date in place; your apps, data and plugins stay:

Terminal window
pnpm antfabric update # core's main, or the ref the instance was created with
pnpm --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:

  1. Fetches core (--ref for a branch or tag; --repo for another repository).
  2. Refuses if core files were edited here, as antfabric check reports them, unless the edit is exactly what the new core has. Nothing of yours is overwritten.
  3. Replaces changed core files, adds new ones and deletes the ones core dropped. Plugins you cloned, added or created, plugins you removed, instances/ and .env files are left alone.
  4. Records the new commit and fingerprint in instances/core.json, runs pnpm install (the lock file keeps your plugins’ dependencies) and pnpm 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.

  1. Core is unchanged (antfabric check).
  2. The manifest is valid (the same checks codegen runs) and every file it names exists.
  3. plugin.yaml’s version equals the plugin’s package.json version.
  4. 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-checks leaves this step out while you are experimenting.

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 .gitignore decides. Outside git, it’s every file. Either way, never .git, .env* (.env.example is kept), .npmrc, key files (*.pem, *.key, *.p12, *.pfx), node_modules or build output. pack prints what it left out;
  • antfabric-plugin.json, written by pack:
{
"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.

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:

Terminal window
antfabric plugin add com.acme.crm-contracts-1.2.0.tgz # → plugins/crm/contracts, nothing selected
antfabric plugin add com.acme.reports-0.3.0.tgz # your plugin, which uses those types

Adding the full plugin later replaces the contracts-only folder with the plugin’s own copy.

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.

Terminal window
pnpm --filter backend db:migrate # the plugin's schema, role and migrations
pnpm dev

The plugin is now an ordinary folder in plugins/: commit it with the instance, or keep the tarball as the release artifact.

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