Developer guide · API v5

Build your own Knosys plugin.

Start with an isolated plugin, add the permissions your feature needs, and test it in the original Knosys interface. API v5 is enabled by default in development and production builds; recovery modes keep plugins disabled.

Current SDK: 5.0.0-alpha.3. This is a private prerelease. You need access to the matching Knosys source checkout to build the host and SDK. The SDK packages are not published on npm, and public marketplace submissions are not open. This guide covers the supported local workflow. The initial plugin offering will remain a prerelease with best-effort support until signed-app pilot acceptance; there is no stable API or guaranteed support response time yet.

1. Create a plugin

Choose the smallest execution model that fits your feature:

• Static: host-rendered declarations and settings, with no executable plugin code.
• Controller: isolated browser JavaScript publishes forms, cards, and other semantic UI rendered by Knosys. A good starting point for most plugins.
• Rich: isolated HTML and browser JavaScript for maps, canvas, and custom interactions. Bundle your own UI dependencies, including React if you use it.

Plugins do not receive Node, the host DOM, filesystem paths, database access, or raw credentials. Declare capabilities and allowed network domains in extension.json. Private plugin storage stays local; canonical workspace changes follow the workspace’s configured sync.

Prepare the matching host and SDK

Use the checkout’s supported Node version (at least 22.12), npm, and desktop native build prerequisites. Run these commands from the repository root. Use a disposable development profile for experiments.

npm install
npm run build:desktop
npm run build -w @knosys/workspace-contracts
npm run build -w @knosys/extension-contracts
npm run build -w @knosys/extension-sdk
npm run build -w @knosys/extension-ui
npm run build -w @knosys/extension-ui-react
mkdir -p .knosys-dev/sdk-alpha3
npm pack -w @knosys/workspace-contracts \
  -w @knosys/extension-contracts -w @knosys/extension-sdk \
  -w @knosys/extension-ui -w @knosys/extension-ui-react \
  --pack-destination .knosys-dev/sdk-alpha3

Scaffold a controller project

Replace the repository path below with your checkout. Choose a new project directory that does not already exist. Unsigned local packages must use an ID beginning with dev..

export KNOSYS_REPO="/absolute/path/to/knosys"
export KNOSYS_SDK_DIR="$KNOSYS_REPO/.knosys-dev/sdk-alpha3"
cd "$KNOSYS_REPO"
npm run extension -- create /tmp/knosys-counter dev.example.counter controller
cd /tmp/knosys-counter
npm install "$KNOSYS_SDK_DIR/knosys-workspace-contracts-0.1.0.tgz" \
  "$KNOSYS_SDK_DIR/knosys-extension-contracts-5.0.0-alpha.3.tgz" \
  "$KNOSYS_SDK_DIR/knosys-extension-sdk-5.0.0-alpha.3.tgz"
npm run build
npm run typecheck

The scaffold includes a manifest, browser entry, build script, and TypeScript configuration. Edit src/index.ts and extension.json, then rebuild. Use static or rich in the create command for another model. A rich project also needs the matching local @knosys/extension-ui tarball; React bindings are optional.

2. Test the behavior, not just the package

From your generated controller project, run:

npm run build
npm run typecheck
npm test
npx --no-install knosys extension pack dist /tmp/knosys-counter-0.1.0.json

The scaffold’s test command validates the built package. It does not certify runtime behavior. Add unit tests for your logic, then test the actual plugin in Knosys. Use the local CLI with --no-install so npm does not fetch a different tool.

In a separate terminal, start the host from the repository with a fresh disposable profile path:

npm run dev:desktop -- --data-root /tmp/knosys-plugin-test-profile

1. Open Settings → Plugins → Install local v5 package. Select the JSON and review its identity, version, and digest.
2. Installation leaves it disabled. Enable it separately, review capabilities, and open its surface. Exercise a real action to confirm execution.
3. Test both cancelled and approved permissions, invalid input, provider errors, offline behavior, and retry controls.
4. Restart the plugin and app. Check saved data, interrupted migrations, update, rollback, and uninstall/reinstall. Uninstall retains data; package rollback does not roll back stored records.
5. Check keyboard navigation, light/dark appearance, narrow windows, and larger disposable datasets. For network plugins, test the real provider and its account requirements before claiming support.

For iteration, watch compiled output with the command below. Run your source build separately. The watcher emits immutable packages to review and reinstall; it does not silently reload or reapprove code.

npx --no-install knosys extension dev dist --watch

3. Package, install, and prepare for review

For local deployment, increment the manifest version whenever package bytes change, rebuild, validate, and pack to a new JSON filename. Install it through Settings → Plugins. Reusing an installed version for changed bytes is refused; the pack command does not overwrite files.

For a future marketplace release, prepare source and revision information, dependency and license inventory, privacy and data-flow disclosures, a support destination, and compatibility evidence. Include permission changes and migration/rollback behavior. Publisher identity and ownership must be reviewed before a public namespace can be used.

Public publishing is not available yet. The CLI’s publish command intentionally refuses uploads. There is no public submission endpoint or npm SDK release to use today. Local development IDs do not establish public publisher ownership.

Maintainers with source access can exercise the signed catalog lifecycle locally with npm run marketplace:demo. It prints a separate disposable profile launch command. This is a fixture for install, update, revocation, and recovery testing, not a production deployment service.

Build an existing project

These are the projects listed in the plugin directory. All commands below run from the repository root after the host/SDK setup above. Use a new output filename if you have already packed that version.

npm run build -w @knosys/plugin-weather
npm run extension -- pack plugins/weather/dist /tmp/knosys-weather-5.0.0-alpha.3.json

npm run build -w @knosys/plugin-maps
npm run extension -- pack plugins/maps/dist /tmp/knosys-maps-5.0.0-alpha.7.json

npm run build:extension-examples -w knosys-desktop
npm run extension -- pack .knosys-dev/extension-packages/notebook /tmp/knosys-notebook-0.1.0.json

npm run build:extension-examples -w knosys-desktop
npm run extension -- pack .knosys-dev/extension-packages/records-v1 /tmp/knosys-records-0.1.0.json

Full reference and deeper examples

The matching source checkout includes the comprehensive documents below in architecture-review/. Use the documents from the same revision as your host and SDK. They include complete code examples, API signatures, brokered network/credential patterns, storage limits, error handling, and migration guidance.

• PLUGIN_API_V5_DEVELOPMENT.md — full development guide and worked controller/rich examples.
• PLUGIN_API_V5_REFERENCE.md — capabilities, methods, errors, and contract limits.
• PLUGIN_SDK_COMPATIBILITY_POLICY.md — exact prerelease pairing and compatibility expectations.
• PLUGIN_MARKETPLACE_OPERATIONS.md — operator review, trust, release, and recovery procedures.

Older guides that expose shared host React, vault paths, or raw API keys describe the retired plugin architecture. New plugins should use API v5’s isolated execution and brokered capabilities.