## For AI Agents/Assistants

The section names and doc paths below can be passed as the `<query>` argument:

```bash
npx @databricks/appkit docs <query>
```

- View documentation index: `npx @databricks/appkit docs`
- View a section: `npx @databricks/appkit docs "appkit-ui API reference"`
- Full index (all API entries): `npx @databricks/appkit docs --full`
- View specific doc: `npx @databricks/appkit docs ./docs/plugins/analytics.md`

---

# AppKit

> Node.js + React SDK for Databricks Apps. Built for humans and AI.


## General docs

- [Getting started](./docs.md): Learn how to get started with AppKit.
- [API reference](./docs/api.md): This section contains the API reference for the AppKit packages.
- [App management](./docs/app-management.md): Manage your AppKit application throughout its lifecycle using the Databricks CLI. This guide covers deploying, starting, stopping, monitoring, and deleting apps.
- [Architecture](./docs/architecture.md): AppKit follows a plugin-based architecture designed for building production-ready Databricks applications. This document provides a high-level overview of the system components and their interactions.
- [Configuration](./docs/configuration.md): This guide covers environment variables and configuration options for AppKit applications.
- [Core principles](./docs/core-principles.md): Learn about the fundamental concepts and principles behind AppKit.
- [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with Agent Skills, and remote tunneling to deployed backends.
- [FAQ](./docs/faq.md): Integrations
- [Plugins](./docs/plugins.md): Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming.

## Development

- [AI-Assisted development](./docs/development/ai-assisted-development.md): AppKit integrates with AI coding assistants through the Agent Skills.
- [LLM Guide](./docs/development/llm-guide.md): This document provides prescriptive guidance for AI coding assistants generating code with Databricks AppKit. It is intentionally opinionated to ensure consistent, production-ready code generation.
- [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

- [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
- [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
- [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
- [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
- [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
- [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
- [Jobs plugin](./docs/plugins/jobs.md): Trigger and monitor Databricks Lakeflow Jobs from your AppKit application.
- [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
- [Model Serving plugin](./docs/plugins/model-serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
- [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
- [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
- [Plugin Stability Tiers](./docs/plugins/stability.md): AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
- [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.

## appkit API reference [collapsed]

- [@databricks/appkit](./docs/api/appkit.md): Core library for building Databricks applications with type-safe SQL queries,
- [Abstract Class: AppKitError](./docs/api/appkit/Class.AppKitError.md): Base error class for all AppKit errors.
- [Class: AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md): Error thrown when authentication fails.
- [Class: ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md): Error thrown when configuration is missing or invalid.
- [Class: ConnectionError](./docs/api/appkit/Class.ConnectionError.md): Error thrown when a connection or network operation fails.
- [Class: ExecutionError](./docs/api/appkit/Class.ExecutionError.md): Error thrown when an operation execution fails.
- [Class: InitializationError](./docs/api/appkit/Class.InitializationError.md): Error thrown when a service or component is not properly initialized.
- [Abstract Class: Plugin<TConfig>](./docs/api/appkit/Class.Plugin.md): Base abstract class for creating AppKit plugins.
- [Class: PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md): Thrown when a policy denies an action.
- [Class: ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md): Central registry for tracking plugin resource requirements.
- [Class: ServerError](./docs/api/appkit/Class.ServerError.md): Error thrown when server lifecycle operations fail.
- [Class: TunnelError](./docs/api/appkit/Class.TunnelError.md): Error thrown when remote tunnel operations fail.
- [Class: ValidationError](./docs/api/appkit/Class.ValidationError.md): Error thrown when input validation fails.
- [Enumeration: RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md): Permission set for Unity Catalog table access
- [Enumeration: ResourceType](./docs/api/appkit/Enumeration.ResourceType.md): Resource types from schema $defs.resourceType.enum
- [Function: appKitServingTypesPlugin()](./docs/api/appkit/Function.appKitServingTypesPlugin.md): Vite plugin to generate TypeScript types for AppKit serving endpoints.
- [Function: appKitTypesPlugin()](./docs/api/appkit/Function.appKitTypesPlugin.md): Vite plugin to generate types for AppKit queries.
- [Function: createApp()](./docs/api/appkit/Function.createApp.md): Bootstraps AppKit with the provided configuration.
- [Function: createLakebasePool()](./docs/api/appkit/Function.createLakebasePool.md): Create a Lakebase pool with appkit's logger integration.
- [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
- [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
- [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
- [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
- [Function: getLakebaseOrmConfig()](./docs/api/appkit/Function.getLakebaseOrmConfig.md): Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
- [Function: getLakebasePgConfig()](./docs/api/appkit/Function.getLakebasePgConfig.md): Get Lakebase connection configuration for PostgreSQL clients.
- [Function: getPluginManifest()](./docs/api/appkit/Function.getPluginManifest.md): Loads and validates the manifest from a plugin constructor.
- [Function: getResourceRequirements()](./docs/api/appkit/Function.getResourceRequirements.md): Gets the resource requirements from a plugin's manifest.
- [Function: getUsernameWithApiLookup()](./docs/api/appkit/Function.getUsernameWithApiLookup.md): Resolves the PostgreSQL username for a Lakebase connection.
- [Function: getWorkspaceClient()](./docs/api/appkit/Function.getWorkspaceClient.md): Get workspace client from config or SDK default auth chain
- [Function: isSQLTypeMarker()](./docs/api/appkit/Function.isSQLTypeMarker.md): Type guard to check if a value is a SQL type marker
- [Interface: BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md): Base configuration interface for AppKit plugins
- [Interface: CacheConfig](./docs/api/appkit/Interface.CacheConfig.md): Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
- [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
- [Interface: EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md): Properties
- [Interface: FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md): Minimal user identity passed to the policy function.
- [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
- [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
- [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
- [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
- [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
- [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
- [Interface: JobsConnectorConfig](./docs/api/appkit/Interface.JobsConnectorConfig.md): Properties
- [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
- [Interface: PluginManifest<TName>](./docs/api/appkit/Interface.PluginManifest.md): Plugin manifest that declares metadata and resource requirements.
- [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
- [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
- [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
- [Interface: ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md): Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instancename, databasename or scope, key).
- [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
- [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
- [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
- [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
- [Interface: TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md): OpenTelemetry configuration for AppKit applications
- [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
- [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
- [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
- [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
- [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on
- [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
- [Type Alias: JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md): Job handle returned by appkit.jobs("etl").
- [Type Alias: JobsExport()](./docs/api/appkit/TypeAlias.JobsExport.md): Public API shape of the jobs plugin.
- [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
- [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
- [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
- [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
- [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
- [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
- [Variable: WRITE_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md): Actions that mutate data.

## appkit-ui API reference [collapsed]

- [@databricks/appkit-ui](./docs/api/appkit-ui.md): The library provides a set of UI primitives for building Databricks apps in React.
- [DataTable](./docs/api/appkit-ui/data/DataTable.md): Production-ready data table with automatic data fetching and state management
- [DirectoryList](./docs/api/appkit-ui/files/DirectoryList.md): Card-wrapped directory listing with loading, error, and empty states
- [FileBreadcrumb](./docs/api/appkit-ui/files/FileBreadcrumb.md): Path-aware breadcrumb navigation built on top of Breadcrumb primitives
- [FileEntry](./docs/api/appkit-ui/files/FileEntry.md): Single file or directory row with icon, name, size, and selection state
- [FilePreviewPanel](./docs/api/appkit-ui/files/FilePreviewPanel.md): Preview panel displaying file metadata, image/text preview, and download/delete actions
- [NewFolderInput](./docs/api/appkit-ui/files/NewFolderInput.md): Inline folder-name input with create/cancel actions
- [GenieChat](./docs/api/appkit-ui/genie/GenieChat.md): Full-featured chat interface for a single Databricks AI/BI Genie space. Handles message streaming, conversation history, and auto-reconnection via SSE.
- [GenieChatInput](./docs/api/appkit-ui/genie/GenieChatInput.md): Auto-expanding textarea input with a send button for chat messages. Submits on Enter (Shift+Enter for newline).
- [GenieChatMessage](./docs/api/appkit-ui/genie/GenieChatMessage.md): Renders a single Genie message bubble with optional expandable SQL query attachments.
- [GenieChatMessageList](./docs/api/appkit-ui/genie/GenieChatMessageList.md): Scrollable message list that renders Genie chat messages with auto-scroll, skeleton loaders, and a streaming indicator.
- [GenieQueryVisualization](./docs/api/appkit-ui/genie/GenieQueryVisualization.md): Renders a chart + data table for a Genie query result.
- [Styling](./docs/api/appkit-ui/styling.md): This guide covers how to style AppKit UI components using CSS variables and theming.
- [Accordion](./docs/api/appkit-ui/ui/Accordion.md): Collapsible content sections organized in a vertical stack
- [Alert](./docs/api/appkit-ui/ui/Alert.md): Displays important information with optional icon and multiple variants
- [AlertDialog](./docs/api/appkit-ui/ui/AlertDialog.md): Modal dialog that interrupts the user with critical information requiring immediate action
- [AspectRatio](./docs/api/appkit-ui/ui/AspectRatio.md): Container that maintains a specific aspect ratio for its content
- [Avatar](./docs/api/appkit-ui/ui/Avatar.md): Displays user profile picture or initials in a circular container
- [Badge](./docs/api/appkit-ui/ui/Badge.md): Small label for displaying status, categories, or counts
- [Breadcrumb](./docs/api/appkit-ui/ui/Breadcrumb.md): Navigation component showing the current page's location in the site hierarchy
- [Button](./docs/api/appkit-ui/ui/Button.md): Clickable button with multiple variants and sizes
- [ButtonGroup](./docs/api/appkit-ui/ui/ButtonGroup.md): Container for grouping related buttons together with shared borders
- [Calendar](./docs/api/appkit-ui/ui/Calendar.md): Date picker component for selecting single dates or date ranges
- [Card](./docs/api/appkit-ui/ui/Card.md): Container for grouping related content with header, body, and footer sections
- [Carousel](./docs/api/appkit-ui/ui/Carousel.md): Slideshow component for cycling through content with navigation controls
- [ChartContainer](./docs/api/appkit-ui/ui/ChartContainer.md): Container for rendering data visualizations using Recharts
- [Checkbox](./docs/api/appkit-ui/ui/Checkbox.md): Checkbox input for selecting multiple options
- [Collapsible](./docs/api/appkit-ui/ui/Collapsible.md): Interactive component that expands and collapses content
- [Command](./docs/api/appkit-ui/ui/Command.md): Command palette for keyboard-driven navigation and actions
- [ContextMenu](./docs/api/appkit-ui/ui/ContextMenu.md): Menu triggered by right-clicking an element
- [Dialog](./docs/api/appkit-ui/ui/Dialog.md): Modal dialog that overlays the page content
- [Drawer](./docs/api/appkit-ui/ui/Drawer.md): Draggable panel that slides in from screen edges
- [DropdownMenu](./docs/api/appkit-ui/ui/DropdownMenu.md): Menu that displays when triggered by a button or element
- [Empty](./docs/api/appkit-ui/ui/Empty.md): Empty state component for displaying no-data scenarios
- [Field](./docs/api/appkit-ui/ui/Field.md): Form field wrapper with label and input positioning
- [FormControl](./docs/api/appkit-ui/ui/FormControl.md): Wrapper for form control elements with accessibility attributes
- [HoverCard](./docs/api/appkit-ui/ui/HoverCard.md): Content card that appears when hovering over an element
- [Input](./docs/api/appkit-ui/ui/Input.md): Text input field for single-line user input
- [InputGroup](./docs/api/appkit-ui/ui/InputGroup.md): Container for combining input fields with addons and buttons
- [InputOTP](./docs/api/appkit-ui/ui/InputOTP.md): One-time password input with individual character slots
- [Item](./docs/api/appkit-ui/ui/Item.md): Flexible container for list items with media, content, and actions
- [Kbd](./docs/api/appkit-ui/ui/Kbd.md): Visual representation of keyboard keys
- [Label](./docs/api/appkit-ui/ui/Label.md): Text label associated with form controls
- [Menubar](./docs/api/appkit-ui/ui/Menubar.md): Horizontal menu bar with dropdown menus
- [NavigationMenu](./docs/api/appkit-ui/ui/NavigationMenu.md): Horizontal navigation menu with dropdown submenus
- [Pagination](./docs/api/appkit-ui/ui/Pagination.md): Navigation component for paginated content
- [Popover](./docs/api/appkit-ui/ui/Popover.md): Floating content panel anchored to a trigger element
- [Progress](./docs/api/appkit-ui/ui/Progress.md): Visual indicator showing task completion percentage
- [RadioGroup](./docs/api/appkit-ui/ui/RadioGroup.md): Group of radio buttons for selecting a single option
- [ResizableHandle](./docs/api/appkit-ui/ui/ResizableHandle.md): Draggable handle for resizing panels
- [ScrollArea](./docs/api/appkit-ui/ui/ScrollArea.md): Container with custom scrollbars for overflow content
- [Select](./docs/api/appkit-ui/ui/Select.md): Dropdown control for selecting a value from a list
- [Separator](./docs/api/appkit-ui/ui/Separator.md): Visual divider line between content sections
- [Sheet](./docs/api/appkit-ui/ui/Sheet.md): Sliding panel that overlays content from screen edges
- [Sidebar](./docs/api/appkit-ui/ui/Sidebar.md): Collapsible navigation sidebar with mobile support
- [Skeleton](./docs/api/appkit-ui/ui/Skeleton.md): Loading placeholder with pulsing animation
- [Slider](./docs/api/appkit-ui/ui/Slider.md): Draggable input for selecting numeric values within a range
- [Spinner](./docs/api/appkit-ui/ui/Spinner.md): Animated loading indicator
- [Switch](./docs/api/appkit-ui/ui/Switch.md): Toggle control for switching between on and off states
- [Table](./docs/api/appkit-ui/ui/Table.md): Structured data display with rows and columns
- [Tabs](./docs/api/appkit-ui/ui/Tabs.md): Tabbed interface for organizing content into separate panels
- [Textarea](./docs/api/appkit-ui/ui/Textarea.md): Multi-line text input field
- [Toaster](./docs/api/appkit-ui/ui/Toaster.md): Toast notification system for displaying temporary messages
- [Toggle](./docs/api/appkit-ui/ui/Toggle.md): Button that toggles between pressed and unpressed states
- [ToggleGroup](./docs/api/appkit-ui/ui/ToggleGroup.md): Group of toggle buttons for selecting one or more options
- [Tooltip](./docs/api/appkit-ui/ui/Tooltip.md): Brief informational message that appears on hover
