Databricks Apps

Databricks Apps Development

FIRST: Use the parent databricks-core skill for CLI basics, authentication, and profile selection.

Is this even a Databricks App? Don't assume an app is the only way to show data. For a simple "dashboard with a few charts" and no app-specific need, the managed AI/BI (Lakeview) dashboard is the simpler path → use the databricks-aibi-dashboards skill, not this one. Reach for a custom Databricks App only when the user needs something AI/BI can't give them — bespoke interactivity/components, write-back, embedded or auth-gated workflows, a Genie/chat surface inside the app — or explicitly asks for an app. If it's genuinely ambiguous, surface both options (managed AI/BI dashboard vs custom app) and let the user choose instead of defaulting to an app. Once an app is the right call, it's fine for this skill to favor an app-based dashboard, and databricks-app-design covers building it well.

For data UI design (required for any data-displaying app): once you've confirmed the user wants a custom-code app (not a managed AI/BI dashboard — see above), if the app shows ANY data — a KPI/overview page, report, chart, table, query results, OR a conversational / chat / Genie natural-language assistant — you MUST use the databricks-app-design skill (alongside this one) to decide layout, charts, KPIs, semantic color, required states, and AI-result trust, and map them to AppKit components. This includes chat/Genie apps, not just static data views — if in doubt, use it.

Build apps that deploy to Databricks Apps platform.

Required Reading by Phase

Generic Guidelines

• App name: ≤26 characters, lowercase letters/numbers/hyphens only (no underscores). dev- prefix adds 4 chars, max 30 total.
• Validation: databricks apps validate --profile <PROFILE> before deploying.
• Smoke tests (AppKit only): ALWAYS update tests/smoke.spec.ts selectors BEFORE running validation. Default template checks for "Minimal Databricks App" heading and "hello world" text — these WILL fail in your custom app. See testing guide.
• Smoke test selectors: use only Playwright locator APIs — getByRole, getByText, getByPlaceholder, getByLabel. getByLabelText does not exist in Playwright (it is a React Testing Library method) and throws TypeError at runtime. See testing guide or npx playwright codegen.
• Smoke test data: keep result sets under the 1 MB analytics-event payload cap. Queries returning thousands of rows cause INVALID_REQUEST: Event exceeds max size of 1048576 bytes and net::ERR_ABORTED, leaving every asserted UI element absent. Use LIMIT or an aggregated query (e.g. COUNT(*) GROUP BY status) — never raw row dumps.
• AppKit version: never override the @databricks/appkit or @databricks/appkit-ui version in package.json — databricks apps init sets the correct version. Do not run npm install @databricks/appkit@<version> unless explicitly asked by the user. If you need a different version, re-scaffold with databricks apps init --version <version>.
• Authentication: covered by parent databricks-core skill.
• AppKit API surface: before writing code that calls AppKit APIs (createApp, plugin shapes, useAnalyticsQuery, useMetricView, etc.), run npx @databricks/appkit docs <section> and use the actual signature. Training data has stale shapes; a single invented signature fails tsc --noEmit during validate. The docs ship with the installed AppKit and are the authoritative source.
• TypeScript casts: never use as unknown as <T> double-assertions — appkit lint enforces no-double-type-assertion and one violation fails the entire validate step. Instead: narrow with Zod (z.infer<typeof schema>), use a runtime type guard, or write a typed mapper function. If a query result needs reshaping, type the row schema via queryKey types rather than casting.

Project Structure (after databricks apps init --features analytics)

• client/src/App.tsx — main React component (start here)
• config/queries/*.sql — SQL query files (queryKey = filename without .sql)
• config/metric-views/definitions.json — governed UC Metric View bindings (optional; see Metric Views)
• server/server.ts — backend entry (onPluginsReady + Express routes)
• tests/smoke.spec.ts — smoke test (⚠️ MUST UPDATE selectors for your app)
• client/src/appKitTypes.d.ts — auto-generated types (npm run typegen)

Project Structure (after databricks apps init --features lakebase)

• server/server.ts — backend with Lakebase pool + Express routes
• client/src/App.tsx — React frontend
• app.yaml — manifest with database resource declaration
• package.json — includes @databricks/lakebase dependency
• Note: No `config/queries/` — Lakebase apps use appkit.lakebase.query() in Express routes, not SQL files

Data Discovery

Before writing any SQL, use the parent databricks-core skill for data exploration — search information_schema by keyword, then batch discover-schema for the tables you need. Do NOT skip this step.

State Storage Guidance (evaluate BEFORE the Decision Gate):

If the user's app description involves storing or persisting data — forms, CRUD operations, user submissions, orders, todos, or other user-generated content — the app likely needs a Lakebase database.

1. Ask the user whether the app needs persistent storage (Lakebase) before scaffolding. Do not silently add Lakebase.
2. If confirmed, ask whether to reuse an existing Lakebase project or create a new one (same as the Genie flow below) — never create one silently. Use the `databricks-lakebase` skill to obtain the branch and database resource names:

• Reusing: list with databricks postgres list-projects, then list-branches / list-databases, and let the user pick the project, branch, and database; confirm which schema the app will own (a fresh/dedicated schema avoids the service-principal ownership conflict).