04 Appkit Plugin Add

Add Plugins to an Existing AppKit Project

Add Lakebase, Analytics, Genie, Files, or Serving plugins to a Databricks AppKit project that has already been scaffolded.

When to Use

• Adding a new plugin to an existing AppKit project
• Integrating PostgreSQL (Lakebase), SQL dashboards (Analytics), natural language queries (Genie), file management (Files), or model serving / agent endpoints (Serving)
• Extending an app that was scaffolded blank or needs an additional plugin

Not for scaffolding a new app. To create a new AppKit project (blank or with plugins), use the 01-appkit-scaffold skill instead.

Before You Begin

IMPORTANT — The upstream AppKit docs are the source of truth, not this skill. AppKit may have plugins beyond those listed here. Always check the upstream docs first to discover all available plugins and get the latest configuration details:

• Plugin docs: https://databricks.github.io/appkit/docs/plugins/
• CLI docs browser: npx @databricks/appkit docs "<plugin-name>"
• Full plugin list: npx @databricks/appkit docs "plugins"

The bundled reference files below cover commonly used plugins as a fallback when the live docs cannot be reached. If the user requests a plugin not listed here, consult the upstream docs directly.

Working in Genie Code (client routing)

This skill is written for the IDE/CLI path. Plugin registration itself — editing server/server.ts, app.yaml, and databricks.yml — is identical on both clients. Only the toolchain commands differ; apply these substitutions and you do not need to re-check per command:

Paths in this skill are relative to apps_lakebase/$APP_NAME — on Genie Code that resolves inside your git-cloned workshop project (artifact_root), never the read-only .assistant/skills copy and never /tmp. See skills/genie-code-environment for the full manifest.

Step 1: Identify Which Plugin to Add

The table below covers plugins bundled with this skill. AppKit may offer additional plugins not listed here — check the upstream docs (npx @databricks/appkit docs "plugins") for the full list.

If the plugin you need is listed above, READ its reference file before proceeding — it contains the import, config, env vars, app.yaml changes, frontend hooks, and gotchas. For any other plugin, consult the upstream docs directly.

MANDATORY: You MUST read the plugin's reference file before making any changes. Do not treat the reference as optional supplementary material. For Lakebase specifically, the reference contains critical Terraform state management warnings that prevent destructive deploy failures. After reading, note any "Critical" or "Keep" warnings in .vibecoding-state.md under a "Critical Notes for Next Phase" section so downstream agents inherit the context.

Step 1b: Verify the Plugin Export Exists (before importing)

Before adding the plugin to server/server.ts, confirm it is exported by your installed AppKit version. The server bundler (tsdown) does not type-check — a nonexistent import bundles silently and only fails at client build or runtime, usually after a long deploy round-trip.

cd apps_lakebase/$APP_NAME
node -e "const m = require('@databricks/appkit'); console.log(typeof m.<pluginName>);"

• function → plugin is available, proceed to Step 2.
• undefined → plugin is not in your installed AppKit version. Do NOT write import { <pluginName> } from "@databricks/appkit" — the bundler will accept it and your deploy will fail silently.
  • If the plugin was recently published to npm: npm install @databricks/appkit@latest @databricks/appkit-ui@latest and rerun the check. If this triggers a package-lock.json regeneration, read 03-appkit-deploy/references/lockfile-and-recreation.md before deploying.
  • If the plugin is not yet published: use a custom proxy fallback. For the Serving plugin specifically, read 06-appkit-serving-wiring/references/custom-proxy-fallback.md. For other plugins, consult the upstream docs for a supported fallback before hand-rolling one.

Confirm the method / hook names you plan to call the same way — inspect the installed .d.ts:

find node_modules/@databricks/appkit -name "*.d.ts" | xargs grep -l "<ExportName>" | head -5

Anti-pattern — "Import it and see if it compiles." The server bundler (tsdown) skips type checking and will silently bundle a broken import. The error surfaces only when the client build runs tsc or the server crashes at runtime — usually after a 2-3 minute deploy round-trip. Always run the node -e check above before writing the import.

Client note — Genie Code: the node -e / find node_modules checks are IDE-only (no local node_modules). Instead, confirm the export name against the AppKit plugin docs (WebFetch https://databricks.github.io/appkit/docs/plugins/), then deploy and treat the server-side build logs (databricks apps logs <name>) as the authoritative signal — a nonexistent import fails the platform build there with the same error.

Step 2: Register the Plugin

In server/server.ts, import the plugin and add it to the plugins array:

import { createApp, server, <pluginName> } from "@databricks/appkit";

await createApp({
  plugins: [
    server(),
    <pluginName>(),
  ],
});

Multiple Plugins

Plugins compose freely — add as many as needed:

import { createApp, server, analytics, lakebase, genie, files, serving } from "@databricks/appkit";

await createApp({
  plugins: [
    server(),
    analytics(),
    lakebase(),
    genie(),
    files(),
    serving(),
  ],
});

Step 3: Configure Environment Variables

Each plugin requires specific environment variables. After reading the plugin reference file, add the required variables to:

1. .env — for local development
2. app.yaml — for deployed apps

See the plugin-specific reference for exact variable names and values.

After editing databricks.yml and app.yaml, run databricks apps validate --profile $PROFILE to catch YAML syntax or resource binding errors before deploy.

Step 4: Frontend Integration

Most plugins provide React hooks and/or components from @databricks/appkit-ui/react:

See the plugin-specific reference for usage examples.

AppKit Documentation (Live)

For the latest API details, component props, and hook signatures:

npx @databricks/appkit docs              # documentation index
npx @databricks/appkit docs "<query>"    # search for a specific topic
npx @databricks/appkit docs --full       # full index with all API entries

Quick Reference

See Also

• Upstream platform skill: databricks-agent-skills / databricks-apps (tracked in upstream_sources).
• AppKit plugin docs: databricks.github.io/appkit/docs/plugins/