databricks-apps

name	databricks-apps
description	Build apps on Databricks Apps platform. Use when asked to create dashboards, data apps, analytics tools, or visualizations. Invoke BEFORE starting implementation.
compatibility	Requires databricks CLI (>= v0.288.0)
metadata	{"version":"0.1.0"}
parent	databricks

Databricks Apps Development

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

Build apps that deploy to Databricks Apps platform.

Required Reading by Phase

Phase	READ BEFORE proceeding
Scaffolding	Parent databricks skill (auth, warehouse discovery); run databricks apps manifest and use its plugins/resources to build databricks apps init with --features and --set (see AppKit section below)
Writing SQL queries	SQL Queries Guide
Writing UI components	Frontend Guide
Using useAnalyticsQuery	AppKit SDK
Adding API endpoints	tRPC Guide

Generic Guidelines

These apply regardless of framework:

• Deployment: databricks apps deploy --profile <PROFILE> (⚠️ USER CONSENT REQUIRED)
• Validation: databricks apps validate --profile <PROFILE> before deploying
• App name: Must be ≤26 characters, lowercase letters/numbers/hyphens only (no underscores). dev- prefix adds 4 chars, max 30 total.
• Smoke tests: 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.
• Authentication: covered by parent databricks skill

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)
• server/server.ts — backend entry (tRPC routers)
• tests/smoke.spec.ts — smoke test (⚠️ MUST UPDATE selectors for your app)
• client/src/appKitTypes.d.ts — auto-generated types (npm run typegen)

Data Discovery

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

Development Workflow (FOLLOW THIS ORDER)

1. Create SQL files in config/queries/
2. Run npm run typegen — verify all queries show ✓
3. Read client/src/appKitTypes.d.ts to see generated types
4. THEN write App.tsx using the generated types
5. Update tests/smoke.spec.ts selectors
6. Run databricks apps validate --profile <PROFILE>

DO NOT write UI code before running typegen — types won't exist and you'll waste time on compilation errors.

When to Use What

• Read data → display in chart/table: Use visualization components with queryKey prop
• Read data → custom display (KPIs, cards): Use useAnalyticsQuery hook
• Read data → need computation before display: Still use useAnalyticsQuery, transform client-side
• Call ML model endpoint: Use tRPC
• Write/update data (INSERT/UPDATE/DELETE): Use tRPC
• ⚠️ NEVER use tRPC to run SELECT queries — always use SQL files in config/queries/

Frameworks

AppKit (Recommended)

TypeScript/React framework with type-safe SQL queries and built-in components.

Official Documentation — the source of truth for all API details:

npx @databricks/appkit docs              # ← ALWAYS start here to see available pages
npx @databricks/appkit docs <path>       # then use paths from the index

DO NOT guess doc paths. Run without args first, pick from the index. Docs are the authority on component props, hook signatures, and server APIs — skill files only cover anti-patterns and gotchas.

App Manifest and Scaffolding

Agent workflow for scaffolding: get the manifest first, then build the init command.

1. Get the manifest (JSON schema describing plugins and their resources):

   databricks apps manifest --profile <PROFILE>
   # Custom template:
   databricks apps manifest --template <GIT_URL> --profile <PROFILE>
   

   The output defines:

   • Plugins: each has a key (plugin ID for --features), plus requiredByTemplate, and resources.
   • requiredByTemplate: If true, that plugin is mandatory for this template — do not add it to --features (it is included automatically); you must still supply all of its required resources via --set. If false or absent, the plugin is optional — add it to --features only when the user's prompt indicates they want that capability (e.g. analytics/SQL), and then supply its required resources via --set.
   • Resources: Each plugin has resources.required and resources.optional (arrays). Each item has resourceKey and fields (object: field name → description/env). Use --set <plugin>.<resourceKey>.<field>=<value> for each required resource field of every plugin you include.

2. Scaffold (DO NOT use npx; use the CLI only):

   databricks apps init --name <NAME> --features <plugin1>,<plugin2> \
     --set <plugin1>.<resourceKey>.<field>=<value> \
     --set <plugin2>.<resourceKey>.<field>=<value> \
     --description "<DESC>" --run none --profile <PROFILE>
   # --run none: skip auto-run after scaffolding (review code first)
   # With custom template:
   databricks apps init --template <GIT_URL> --name <NAME> --features ... --set ... --profile <PROFILE>
   

   • Required: --name, --profile. Name: ≤26 chars, lowercase letters/numbers/hyphens only. Use --features only for optional plugins the user wants (plugins with requiredByTemplate: false or absent); mandatory plugins must not be listed in .

DO NOT guess plugin names, resource keys, or property names — always derive them from databricks apps manifest output. Example: if the manifest shows plugin analytics with a required resource resourceKey: "sql-warehouse" and fields: { "id": ... }, include --set analytics.sql-warehouse.id=<ID>.

READ AppKit Overview for project structure, workflow, and pre-implementation checklist.

Common Scaffolding Mistakes

# ❌ WRONG: name is NOT a positional argument
databricks apps init --features analytics my-app-name
# → "unknown command" error

# ✅ CORRECT: use --name flag
databricks apps init --name my-app-name --features analytics --set "..." --profile <PROFILE>

Directory Naming

databricks apps init creates directories in kebab-case matching the app name. App names must be lowercase with hyphens only (≤26 chars).

Other Frameworks

Databricks Apps supports any framework that can run as a web server (Flask, FastAPI, Streamlit, Gradio, etc.). Use standard framework documentation - this skill focuses on AppKit.