# Plugin Stability Tiers

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

## Tiers[​](#tiers "Direct link to 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-path "Direct link to Promotion Path")

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

```text
beta ──→ ga

```

## Usage[​](#usage "Direct link to Usage")

### Importing Plugins by Tier[​](#importing-plugins-by-tier "Direct link to Importing Plugins by Tier")

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

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

```

### UI Components[​](#ui-components "Direct link to UI Components")

`@databricks/appkit-ui` mirrors the same pattern:

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

```

## CLI Commands[​](#cli-commands "Direct link to CLI Commands")

### Listing Plugins with Stability[​](#listing-plugins-with-stability "Direct link to Listing Plugins with Stability")

```bash
npx appkit plugin list

```

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

### Creating a Plugin with Stability[​](#creating-a-plugin-with-stability "Direct link to Creating a Plugin with Stability")

```bash
npx appkit plugin create

```

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

### Promoting a Plugin[​](#promoting-a-plugin "Direct link to Promoting a Plugin")

```bash
# 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[​](#manifest-field "Direct link to Manifest Field")

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

```json
{
  "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)[​](#template-manifest-appkitpluginsjson "Direct link to 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.

```json
{
  "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[​](#for-third-party-plugin-authors "Direct link to 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)[​](#for-first-party-plugin-authors-appkit-monorepo "Direct link to 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:

```bash
# 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

```