diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 08d64d8..22788cb 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -4,5 +4,19 @@ This section contains the API reference for the AppKit packages. ## Modules -- [`appkit`](appkit/index.md) - Core library -- [`appkit-ui`](appkit-ui/index.md) - UI components library +- [`appkit`](appkit/index.md) - Core library. Provides the core functionality for building Databricks applications. +- [`appkit-ui`](appkit-ui/index.md) - UI components library. Provides a set of UI primitives for building Databricks apps in [React](https://react.dev/). + +## Getting started + +To learn how to get started with AppKit, see the [getting started guide](../index.md) for AI-assisted and manual quick start options. + +## Installation + +To install the AppKit packages into your existing JavaScript/TypeScript project, use `npm` or your package manager of choice: + +```bash +npm install @databricks/appkit +npm install @databricks/appkit-ui +``` + diff --git a/docs/docs/core-concepts/principles.md b/docs/docs/core-concepts/principles.md index 277e508..c4e0e87 100644 --- a/docs/docs/core-concepts/principles.md +++ b/docs/docs/core-concepts/principles.md @@ -1,24 +1,39 @@ # Principles +Learn about the fundamental concepts and principles behind AppKit. + ## 1. Highly Opinionated - AppKit must provide a clear path with best practices for building Databricks - applications. We provide strong defaults, with advanced customization when needed. + +AppKit must provide a clear path with best practices for building Databricks +applications. We provide strong defaults, with advanced customization when needed. + ## 2. Built for Application Use Cases - This SDK is for application development, not infrastructure management. - Databricks' internal implementation details must be abstracted. We're building an - application SDK, not a service wrapper. + +This SDK is for application development, not infrastructure management. +Databricks' internal implementation details must be abstracted. We're building an +application SDK, not a service wrapper. + ## 3. Delightful Developer Experience - Every interface, doc, example, tool, and implementation must provide developer joy. Combined with the Highly Opinionated principle, this creates a true plug-and-play experience. + +Every interface, doc, example, tool, and implementation must provide developer joy. Combined with the Highly Opinionated principle, this creates a true plug-and-play experience. + ## 4. Zero-Trust Security - Minimize exposed surface area, fail safely by default, and validate all inputs. - AppKit must always have a zero-trust mindset. + +Minimize exposed surface area, fail safely by default, and validate all inputs. +AppKit must always have a zero-trust mindset. + ## 5. Optimized for Humans and AI - Developers and LLMs both use this SDK. Every API must be discoverable, - self-documenting, and inferable by both types of users. Test with both. + +Developers and LLMs both use this SDK. Every API must be discoverable, +self-documenting, and inferable by both types of users. Test with both. + ## 6. Production-Ready from Day One - Even the smallest feature can be used by enterprise users, so everything - shipped must be production-ready. Observability, reliability, and scalability - since day one. + +Even the smallest feature can be used by enterprise users, so everything +shipped must be production-ready. Observability, reliability, and scalability +since day one. + ## 7. Layered Extensibility + AppKit provides high-level plugins, low-level primitives, and extension points for custom plugins. It integrates into any application architecture and never blocks your path forward. diff --git a/docs/docs/index.md b/docs/docs/index.md index b1aef0a..adcaedd 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -2,12 +2,88 @@ sidebar_position: 1 --- -# Getting started +# Getting Started ## Introduction -## Installation +AppKit is a TypeScript SDK for building production-ready Databricks applications with a plugin-based architecture. It provides opinionated defaults, built-in observability, and seamless integration with Databricks services. -## Usage +AppKit simplifies building data applications on Databricks by providing: -## Deployment +- **Plugin architecture**: Modular design with built-in server and analytics plugins +- **Type safety**: End-to-end TypeScript with automatic query type generation +- **Production-ready features**: Built-in caching, telemetry, retry logic, and error handling +- **Developer experience**: Remote hot reload, file-based queries, optimized for AI-assisted development +- **Databricks native**: Seamless integration with SQL Warehouses, Unity Catalog, and other workspace resources + +## Prerequisites + +- [Node.js](https://nodejs.org) +- Databricks CLI: install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial). + +## Quick start options + +There are two ways to get started with AppKit: + +- **AI-assisted** (recommended): Use an AI coding assistant connected via the Databricks MCP server to explore data, run CLI commands, and scaffold your app interactively. +- **Manual**: Use the Databricks CLI directly to create, bootstrap, and deploy your app. + +Choose the path that best fits your workflow; both approaches produce the same kind of AppKit-based Databricks application. + +## AI-first quick start + +Databricks AppKit is designed to work with AI coding assistants through the Databricks MCP server. + +Install the Databricks MCP server and configure it for use with your preferred AI assistant: + +```bash +databricks experimental apps-mcp install +``` + +Once configured for your development environment, you can use your AI assistant to create and deploy new Databricks applications, as well as to iteratively evolve your app’s codebase. + +The MCP server exposes the following capabilities: + +- **Data exploration**: Query catalogs, schemas, tables, and execute SQL +- **CLI command execution**: Run bundle, apps, and workspace operations +- **Workspace resource discovery**: Inspect and navigate workspace resources + +## Manual quick start + +Learn how to create and deploy a sample Databricks application that uses AppKit with the Databricks CLI. + +### Create a new Databricks app + +Run the following command to create a new Databricks application: + +```sh +databricks apps create {application-name} +``` + +This creates a new Databricks application named `{application-name}` in the current workspace. + +### Bootstrap the app codebase with AppKit + +Run the following command to bootstrap the app codebase: + +```sh +databricks experimental appkit init +``` + +Follow the prompts to bootstrap the app codebase in the current working directory. +This creates a complete TypeScript project with Tailwind CSS, React, and AppKit installed out of the box. + +### Deploy the app to Databricks + +Run the following command to deploy the app to Databricks: + +```sh +databricks experimental appkit deploy . +``` + +This deploys the sample app to Databricks. + +## Next steps + +- **[Core Concepts](./core-concepts/principles)**: Learn about AppKit's design principles and architecture +- **[API Reference](./api/appkit/)**: Explore the complete API documentation