@databricks/appkit-ui 0.21.0 → 0.22.0

package/docs/app-management.md

@@ -5,7 +5,7 @@ Manage your AppKit application throughout its lifecycle using the Databricks CLI
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
 ## Create app[​](#create-app "Direct link to Create app")
 

package/docs/architecture.md

@@ -59,7 +59,7 @@ The Node.js backend layer built with `@databricks/appkit`:
 Integration with Databricks services:
 
 * **SQL Warehouses**: Execute analytical queries with Arrow or JSON format
-* **Lakebase V1 (Provisioned)**: Access data from Lakebase Provisioned. Support for Lakebase Autoscaling coming soon.
+* **Lakebase Autoscaling**: OLTP database access with automatic OAuth token refresh
 
 ## See also[​](#see-also "Direct link to See also")
 

package/docs/development/ai-assisted-development.md

@@ -3,7 +3,7 @@
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 AppKit integrates with AI coding assistants through the Agent Skills.
@@ -13,7 +13,7 @@ AppKit integrates with AI coding assistants through the Agent Skills.
 To install the Databricks Agent Skills for your preferred AI assistant, run:
 
 ```bash
-databricks experimental aitools skills install
+databricks experimental aitools install
 
 ```
 

package/docs/development/local-development.md

@@ -3,7 +3,7 @@
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 Once your app is bootstrapped according to the [Manual quick start](./docs.md#manual-quick-start) guide, you can start the development server with hot reload for both UI and backend code.

package/docs/development/remote-bridge.md

@@ -3,7 +3,7 @@
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.

package/docs/development/templates.md

@@ -0,0 +1,93 @@
+# Templates
+
+AppKit uses a template system powered by the Databricks CLI's `databricks apps init` command. Templates define the project structure, and `.tmpl` files are processed with Go's `text/template` engine to generate customized output.
+
+## How `.tmpl` files work[​](#how-tmpl-files-work "Direct link to how-tmpl-files-work")
+
+Any file ending in `.tmpl` is processed by the CLI during `databricks apps init`:
+
+1. The `.tmpl` suffix is stripped (e.g. `.env.tmpl` → `.env`)
+2. Go template expressions are evaluated and substituted
+3. The rendered file is written to the output directory
+
+Files named with a `_` prefix are renamed to `.` prefix (e.g. `_gitignore` → `.gitignore`).
+
+### Template variables[​](#template-variables "Direct link to Template variables")
+
+| Variable          | Description                                                                  |
+| ----------------- | ---------------------------------------------------------------------------- |
+| `.projectName`    | Project name from `--name` or interactive prompt                             |
+| `.workspaceHost`  | Databricks workspace URL                                                     |
+| `.profile`        | Databricks CLI profile name (empty if using host-based auth)                 |
+| `.appDescription` | App description                                                              |
+| `.plugins.<name>` | Non-nil for each selected plugin, enabling conditionals                      |
+| `.dotEnv.content` | Generated `.env` content from plugin resources                               |
+| `.dotEnv.example` | Generated `.env.example` content with placeholders                           |
+| `.bundle.*`       | Generated `databricks.yml` sections (variables, resources, target variables) |
+| `.appEnv`         | Generated `app.yaml` env entries                                             |
+
+### Conditional content[​](#conditional-content "Direct link to Conditional content")
+
+Use Go template conditionals to include/exclude code based on selected plugins:
+
+```go
+{{- if .plugins.analytics}}
+import { analytics } from '@databricks/appkit';
+{{- end}}
+
+```
+
+## `appkit.plugins.json`[​](#appkitpluginsjson "Direct link to appkitpluginsjson")
+
+The plugin manifest drives the CLI's behavior during `databricks apps init`:
+
+* **Plugin selection UI** — selectable plugins shown in the interactive prompt
+* **Resource prompts** — required/optional resources prompt the user for values (e.g. SQL Warehouse ID)
+* **`.dotEnv` population** — resource fields with an `env` property are written to `.env`
+* **`app.yaml` generation** — resource fields produce `env` + `valueFrom` entries
+* **`databricks.yml` generation** — resource fields produce bundle variables and app resource entries
+
+### Resource field properties[​](#resource-field-properties "Direct link to Resource field properties")
+
+Each resource field in the manifest can have these properties:
+
+| Property       | Description                                                                         |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `env`          | Environment variable name written to `.env` and `app.yaml`                          |
+| `description`  | Shown in the interactive prompt and bundle variable description                     |
+| `localOnly`    | Only written to `.env` for local dev; excluded from `app.yaml` and bundle variables |
+| `bundleIgnore` | Excluded from `databricks.yml` variables (but still in `.env`)                      |
+| `value`        | Default value used when no user input is provided                                   |
+| `resolve`      | Auto-populated by CLI from API calls instead of prompting (see below)               |
+| `examples`     | Example values shown in field descriptions                                          |
+
+### Resolvers[​](#resolvers "Direct link to Resolvers")
+
+Fields with a `resolve` property are auto-populated by the CLI from API calls rather than user prompts. The format is `<type>:<field>`.
+
+Currently only the `postgres` resource type has a resolver. Given the user-provided `branch` and `database` resource names, it derives:
+
+| Resolve key             | Description                                                 |
+| ----------------------- | ----------------------------------------------------------- |
+| `postgres:host`         | Postgres host from the branch's read-write endpoint         |
+| `postgres:databaseName` | Postgres database name from the database resource           |
+| `postgres:endpointPath` | Lakebase endpoint resource name from the branch's endpoints |
+
+Example field definition:
+
+```json
+{
+  "host": {
+    "env": "PGHOST",
+    "localOnly": true,
+    "resolve": "postgres:host",
+    "description": "Postgres host for local development."
+  }
+}
+
+```
+
+## See also[​](#see-also "Direct link to See also")
+
+* [Plugin management](./docs/plugins/plugin-management.md) — `appkit plugin sync`, `appkit plugin create`
+* [Configuration](./docs/configuration.md) — environment variables

package/docs/development.md

@@ -5,7 +5,7 @@ AppKit provides multiple development workflows to suit different needs: local de
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 ## Development flows[​](#development-flows "Direct link to Development flows")

package/docs/plugins/caching.md

@@ -16,7 +16,9 @@ await createApp({
 
 ```
 
-Storage auto-selects **Lakebase V1 (Provisioned) persistent cache when healthy**, otherwise falls back to in-memory. Support for Lakebase Autoscaling coming soon.
+Storage auto-selects **Lakebase Autoscaling persistent cache when healthy**, otherwise falls back to in-memory.
+
+The database-backed cache requires the same Lakebase environment variables as the [Lakebase plugin](./docs/plugins/lakebase.md#environment-variables) (`PGHOST`, `PGDATABASE`, `LAKEBASE_ENDPOINT`, `PGSSLMODE`).
 
 ## Plugin-level caching[​](#plugin-level-caching "Direct link to Plugin-level caching")
 

package/docs/plugins/execution-context.md

@@ -42,4 +42,4 @@ Exported from `@databricks/appkit`:
 
 ## Development mode behavior[​](#development-mode-behavior "Direct link to Development mode behavior")
 
-In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and falls back to the service principal.
+In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and skips user impersonation — the operation runs with the default credentials configured for the app instead.

package/docs/plugins/lakebase.md

@@ -17,7 +17,7 @@ The easiest way to get started with the Lakebase plugin is to use the Databricks
 ### Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 * A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.
 
 ### Steps[​](#steps "Direct link to Steps")

package/docs.md

@@ -19,7 +19,7 @@ AppKit simplifies building data applications on Databricks by providing:
 ## Prerequisites[​](#prerequisites "Direct link to Prerequisites")
 
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
-* Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+* Databricks CLI (v0.295.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
 ## Quick start options[​](#quick-start-options "Direct link to Quick start options")
 
@@ -37,7 +37,7 @@ Databricks AppKit is designed to work with AI coding assistants through Agent Sk
 Install Agent Skills and configure it for use with your preferred AI assistant:
 
 ```bash
-databricks experimental aitools skills install
+databricks experimental aitools install
 
 ```
 

package/llms.txt

@@ -36,6 +36,7 @@ npx @databricks/appkit docs <query>
 - [Local development](./docs/development/local-development.md): Once your app is bootstrapped according to the Manual quick start guide, you can start the development server with hot reload for both UI and backend code.
 - [Project setup](./docs/development/project-setup.md): This guide covers the recommended project structure and scaffolding for AppKit applications.
 - [Remote Bridge](./docs/development/remote-bridge.md): Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
+- [Templates](./docs/development/templates.md): AppKit uses a template system powered by the Databricks CLI's databricks apps init command. Templates define the project structure, and .tmpl files are processed with Go's text/template engine to generate customized output.
 - [Type generation](./docs/development/type-generation.md): AppKit can automatically generate TypeScript types for your SQL queries, providing end-to-end type safety from database to UI.
 
 ## Plugins

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -19,7 +19,8 @@
     "llms.txt",
     "README.md",
     "DCO",
-    "NOTICE.md"
+    "NOTICE.md",
+    "sbom.cdx.json"
   ],
   "exports": {
     "./js": "./dist/js/index.js",
@@ -38,55 +39,56 @@
     "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
-    "@radix-ui/react-accordion": "^1.2.12",
-    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-aspect-ratio": "^1.1.8",
-    "@radix-ui/react-avatar": "^1.1.11",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-collapsible": "^1.1.12",
-    "@radix-ui/react-context-menu": "^2.2.16",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-hover-card": "^1.1.15",
-    "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-menubar": "^1.1.16",
-    "@radix-ui/react-navigation-menu": "^1.2.14",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-progress": "^1.1.8",
-    "@radix-ui/react-radio-group": "^1.3.8",
-    "@radix-ui/react-scroll-area": "^1.2.10",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-toggle": "^1.1.10",
-    "@radix-ui/react-toggle-group": "^1.1.11",
-    "@radix-ui/react-tooltip": "^1.2.8",
-    "@tanstack/react-table": "^8.21.3",
-    "apache-arrow": "^21.1.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "cmdk": "^1.1.1",
-    "echarts": "^6.0.0",
-    "echarts-for-react": "^3.0.5",
-    "embla-carousel-react": "^8.6.0",
-    "input-otp": "^1.4.2",
-    "lucide-react": "^0.554.0",
-    "marked": "^17.0.3",
-    "next-themes": "^0.4.6",
-    "react-day-picker": "^9.11.3",
-    "react-hook-form": "^7.68.0",
-    "react-resizable-panels": "^3.0.6",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.4.0",
-    "vaul": "^1.1.2",
-    "@ast-grep/napi": "^0.37.0",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "@clack/prompts": "^1.0.1",
-    "commander": "^12.1.0"
+    "@radix-ui/react-accordion": "1.2.12",
+    "@radix-ui/react-alert-dialog": "1.1.15",
+    "@radix-ui/react-aspect-ratio": "1.1.8",
+    "@radix-ui/react-avatar": "1.1.11",
+    "@radix-ui/react-checkbox": "1.3.3",
+    "@radix-ui/react-collapsible": "1.1.12",
+    "@radix-ui/react-context-menu": "2.2.16",
+    "@radix-ui/react-dialog": "1.1.15",
+    "@radix-ui/react-dropdown-menu": "2.1.16",
+    "@radix-ui/react-hover-card": "1.1.15",
+    "@radix-ui/react-label": "2.1.8",
+    "@radix-ui/react-menubar": "1.1.16",
+    "@radix-ui/react-navigation-menu": "1.2.14",
+    "@radix-ui/react-popover": "1.1.15",
+    "@radix-ui/react-progress": "1.1.8",
+    "@radix-ui/react-radio-group": "1.3.8",
+    "@radix-ui/react-scroll-area": "1.2.10",
+    "@radix-ui/react-select": "2.2.6",
+    "@radix-ui/react-separator": "1.1.8",
+    "@radix-ui/react-slider": "1.3.6",
+    "@radix-ui/react-slot": "1.2.4",
+    "@radix-ui/react-switch": "1.2.6",
+    "@radix-ui/react-tabs": "1.1.13",
+    "@radix-ui/react-toggle": "1.1.10",
+    "@radix-ui/react-toggle-group": "1.1.11",
+    "@radix-ui/react-tooltip": "1.2.8",
+    "@tanstack/react-table": "8.21.3",
+    "apache-arrow": "21.1.0",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "cmdk": "1.1.1",
+    "dompurify": "3.3.3",
+    "echarts": "6.0.0",
+    "echarts-for-react": "3.0.5",
+    "embla-carousel-react": "8.6.0",
+    "input-otp": "1.4.2",
+    "lucide-react": "0.554.0",
+    "marked": "17.0.3",
+    "next-themes": "0.4.6",
+    "react-day-picker": "9.12.0",
+    "react-hook-form": "7.68.0",
+    "react-resizable-panels": "3.0.6",
+    "sonner": "2.0.7",
+    "tailwind-merge": "3.4.0",
+    "vaul": "1.1.2",
+    "@ast-grep/napi": "0.37.0",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "@clack/prompts": "1.0.1",
+    "commander": "12.1.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -94,13 +96,13 @@
     "recharts": "^2.0.0 || ^3.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "recharts": "^2.15.4",
-    "tailwindcss": "^4.0.14",
-    "tw-animate-css": "^1.4.0"
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "recharts": "2.15.4",
+    "tailwindcss": "4.1.17",
+    "tw-animate-css": "1.4.0"
   },
   "publishConfig": {},
   "bin": {