Plugin Stability Tiers

AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.

Tiers

Tier	Import Path	Contract
Beta	@databricks/appkit/beta	API may change between minor releases. On a path to GA.
GA	@databricks/appkit	Generally available. Production ready. Follows semver strictly.

The import path is the primary stability signal. Importing from /beta is explicit consent to potential breaking changes.

Promotion Path

Promotion is one-way. Plugins can enter at any tier.

beta ──→ ga

Usage

Importing Plugins by Tier

// GA plugins
import { server, analytics } from "@databricks/appkit";

// Beta plugins
import { someBetaPlugin } from "@databricks/appkit/beta";

UI Components

@databricks/appkit-ui mirrors the same pattern:

import { SomeComponent } from "@databricks/appkit-ui/react/beta";
import { someUtil } from "@databricks/appkit-ui/js/beta";

CLI Commands

Listing Plugins with Stability

npx appkit plugin list

The output includes a STABILITY column showing each plugin's tier.

Creating a Plugin with Stability

npx appkit plugin create

The interactive flow prompts for a stability level (defaults to GA).

Promoting a Plugin

# Promote from beta to GA
npx appkit plugin promote my-plugin --to ga

# Preview changes without modifying files
npx appkit plugin promote my-plugin --to ga --dry-run

The promote command:

• Updates the plugin's manifest.json stability field
• Rewrites import paths across your project's .ts/.tsx files
• Runs plugin sync to update appkit.plugins.json

Options:

• --dry-run -- Show what would change without writing
• --skip-imports -- Only update the manifest
• --skip-sync -- Don't auto-run sync
• --allow-installed -- Allow promoting a plugin that lives only under node_modules (advanced)

Manifest Field

The stability field in manifest.json is optional. When absent, the plugin is considered GA.

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "An in-development feature",
  "stability": "beta",
  "resources": { "required": [], "optional": [] }
}

Valid values: "beta", "ga".

Template Manifest (appkit.plugins.json)

When plugin sync discovers non-GA plugins, it includes their stability in the output. That is true for every discovery path: plugins resolved from your server file, from --plugins-dir / local plugin trees, and from known packages under node_modules (for example @databricks/appkit). The tier in each plugin’s manifest.json is always reflected in the synced template manifest when it is not GA.

{
  "version": "1.1",
  "plugins": {
    "my-plugin": {
      "name": "my-plugin",
      "stability": "beta",
      "package": "@databricks/appkit"
    }
  }
}

Only GA plugins can be marked requiredByTemplate. Non-GA plugins always remain optional during init.

For Third-Party Plugin Authors

The import path (/beta) only applies to first-party plugins shipped inside @databricks/appkit. Third-party plugins declare stability via the stability field in their manifest.json. CLI tooling (plugin list, plugin sync) surfaces this information to users.

For First-Party Plugin Authors (AppKit Monorepo)

Inside the AppKit monorepo, each plugin's manifest.json stability field is the single source of truth for which subpath ships the plugin. Two build-time generators read every packages/appkit/src/plugins/<name>/manifest.json:

• tools/generate-plugin-entries.ts writes the runtime export barrels:
  • packages/appkit/src/plugins/ga-exports.generated.ts — re-exports of GA plugins, included by src/index.ts (the @databricks/appkit entry).
  • packages/appkit/src/plugins/beta-exports.generated.ts — re-exports of beta plugins, included by src/beta.ts (the @databricks/appkit/beta entry).
• tools/generate-plugin-doc-banners.ts injects (or removes) a :::warning Beta plugin admonition at the top of each plugin's docs page (docs/docs/plugins/<name>.md) so a plugin's documented stability follows its manifest. The script only writes under docs/docs/plugins/: each manifest name must match the plugin schema pattern (^[a-z][a-z0-9-]*$), and resolved doc paths are checked so a malformed name cannot escape that directory.

All generated artifacts are committed and verified by CI; an out-of-date file fails the Check generated types are up to date step.

The appkit plugin promote command detects monorepo context (presence of tools/generate-plugin-entries.ts) and re-runs the generator after updating the manifest, so the runtime exports, the synced appkit.plugins.json, and the manifest can never drift apart.

To move a built-in plugin between tiers manually:

# Edit packages/appkit/src/plugins/<name>/manifest.json
# Set "stability": "beta" (or remove the field for GA)
pnpm run generate:types   # regenerates schema/registry types, export barrels, and doc banners
pnpm sync:template        # regenerates template/appkit.plugins.json