Developing a plugin in a separate repository

A plugin that lives in its own repository can keep the exact same imports as in-repo plugins (@app/kernel/plugin-api, @app/kernel/store) and still typecheck without cloning the framework sources: install the published types package and map the aliases in tsconfig.json.

The framework generates a types-only npm package from src/kernel/:

bun run plugin-types:build

This produces packages/plugin-api/dist/index.d.ts — a single, self-contained declaration bundle of the whole plugin surface (PluginContext, PluginDefinition, SliceHandle, Services, settings, value types, tables, lists, manifests, transactions…) with react kept external. It is regenerated from the framework sources, never hand-edited. The npm scope is a placeholder (@scfloworg/plugin-api): rename it freely when publishing — nothing in plugin code changes, because @app/... imports are tsconfig aliases, not npm packages.

Installing the types

# from the public registry
npm install -D @scfloworg/plugin-api

# while iterating, without publishing — from the framework repo:
bun run plugin-types:build
cd packages/plugin-api && npm pack      # → scaffold-plugin-api-0.1.0.tgz
npm install -D /path/to/scaffold-plugin-api-0.1.0.tgz

# or a Git repository that commits packages/plugin-api/dist/
npm install -D github:<org>/<repo>#<branch>

Wiring the plugin’s tsconfig

{
  "compilerOptions": {
    "paths": {
      // only the public surface resolves; kernel internals stay out of reach
      "@app/kernel/plugin-api": ["./node_modules/@scfloworg/plugin-api/dist/index.d.ts"],
      "@app/kernel/store": ["./node_modules/@scfloworg/plugin-api/dist/index.d.ts"]
    }
  }
}

Types never enter the bundle: the builder aliases react, and type-only imports disappear at compile time. The package is used by the TypeScript compiler only (tsgo --noEmit); plugin:build / plugin:watch work exactly as for in-repo plugins, pointing at your own src/.

The in-repo scaffold (plugin:new) generates a tsconfig.json with comments showing both modes: same-repo (paths to ../../src) and external-repo (paths to the npm package).