apx - SKILL.md Agent Skill

name: apx description: Quick reference for building full-stack Databricks Apps with apx (React + FastAPI). Use when working on apx projects, creating routes, adding components, or managing dev servers. user-invocable: true

apx Toolkit

apx is the toolkit for building full-stack Databricks Apps with React + FastAPI.

Prerequisites

Before using apx, verify the CLI is installed:

apx --version

If not installed:

macOS/Linux: curl -fsSL https://databricks-solutions.github.io/apx/install.sh | sh
Windows (PowerShell): irm https://databricks-solutions.github.io/apx/install.ps1 | iex

When to Use This Skill

Working on a project that uses apx (check for pyproject.toml with apx entrypoint or databricks.yml)
Creating or modifying FastAPI routes, Pydantic models, or React pages
Managing dev servers, checking errors, or viewing logs
Adding shadcn/ui components or frontend dependencies
Deploying or debugging Databricks Apps

Quick Start

The project follows standard apx conventions. Use MCP tools and pattern files instead of exploring the codebase:

routes — Call this first to see all API routes. Do NOT read source files to explore.
docs — Search SDK docs for the method you need (e.g. "jobs list") before writing any ws.* call.
Follow patterns — See backend-patterns.md for models, routers, pagination, and DI.
refresh_openapi — Run after adding/modifying backend routes so frontend hooks update automatically.
check — Run type checks to verify correctness after changes.

Project Structure

src/<app>/
├── ui/                    # React + Vite frontend
│   ├── components/        # UI components (shadcn/ui)
│   ├── routes/            # @tanstack/react-router pages
│   ├── lib/               # Utilities (api client, selector)
│   └── styles/            # CSS styles
└── backend/               # FastAPI backend
    ├── app.py             # Main FastAPI app
    ├── router.py          # API routes
    ├── models.py          # Pydantic models
    └── core.py            # Config, logging, Dependency class, bootstrap

CLI Commands

Command	Description
`apx dev start`	Start all dev servers (backend + frontend + OpenAPI watcher)
`apx dev stop`	Stop all dev servers
`apx dev status`	Check status of running servers
`apx dev check`	Check for TypeScript/Python errors
`apx dev logs`	View recent logs (default: last 10m)
`apx dev logs -f`	Follow/stream logs in real-time
`apx build`	Build for production
`apx bun <args>`	Run bun commands (install, add, etc.)
`apx components add <name>`	Add a shadcn/ui component
`apx init --as-member`	Add apx to an existing project as a uv workspace member
`apx dev apply <addon>`	Apply an addon to an existing project

Addons

Addons extend the base project with additional capabilities (UI, assistant rules, database integrations, etc.). To list available addons, run apx dev apply --help. To apply an addon to an existing project: apx dev apply <addon> (e.g. apx dev apply lakebase). During apx init, addons are selected interactively or via --addons=ui,claude,sidebar.

Adding to an Existing Project

Use --as-member to add apx into an existing Python project or monorepo as a uv workspace member:

# Recommended: explicit member path
apx init --as-member=packages/app

# Or just auto-detect (when pyproject.toml exists without [tool.apx])
apx init

Auto-detected: running apx init in a directory with an existing pyproject.toml (without [tool.apx]) automatically uses member mode with default path packages/app.

The command:

Creates app files in the member subdirectory (e.g. packages/app)
Configures [tool.uv.workspace] in the root pyproject.toml
Initializes git at the workspace root if needed

MCP Tools

When the apx MCP server is running, these tools are available:

Tool	Description
`start`	Start the development server and return its URL. Call before testing UI or API changes.
`stop`	Stop the development server.
`restart`	Restart the development server (preserves port). Use after backend code changes.
`logs`	Fetch recent dev server logs. Use to diagnose runtime errors or startup issues.
`check`	Run TypeScript and Python type checks in parallel. Returns categorized errors. Call after making changes to verify correctness.
`routes`	List all API routes with their parameters, request/response schemas, and generated hook names. Call this first to understand the project's API surface before reading source files.
`get_route_info`	Get a complete frontend code example for a specific API route, including Suspense/ErrorBoundary scaffold and correct hook usage with parameters. Call this before writing any frontend code that uses an API route. Pass the operation_id from the routes tool.
`refresh_openapi`	Regenerate the OpenAPI schema and TypeScript API client from backend routes. Run after adding or modifying backend routes.
`search_registry_components`	Semantic search for UI components across configured registries (shadcn, etc). Returns component IDs usable with add_component.
`add_component`	Install a UI component into the project. Accepts 'component-name' (default registry) or '@registry-name/component-name'.
`list_registry_components`	List all available components in a registry. Defaults to shadcn registry if none specified.
`docs`	Search Databricks SDK documentation for Python code examples and API references. Always call this before writing any Databricks SDK (ws.*) call to verify the correct method signature.
`databricks_apps_logs`	Fetch logs from a deployed Databricks App using the Databricks CLI. Use for debugging deployed (not local dev) issues.
`feedback_prepare`	Prepare a feedback issue for review. Returns the formatted title, body, and a browser URL. Call `feedback_submit` to create the GitHub issue.
`feedback_submit`	Submit a prepared feedback issue as a public GitHub issue. Pass the exact title and body returned by `feedback_prepare`.

Recommended Workflow

routes — List all API routes to understand the project's API surface
get_route_info — Get a complete code example for a specific route
search_registry_components / add_component — Find and install UI components
refresh_openapi — Regenerate the API client after backend route changes
check — Run type checks to verify correctness
start / restart — Start or restart the dev server to test changes
logs — Diagnose runtime errors if something goes wrong

Do's and Don'ts

OpenAPI client auto-regenerates on code changes when dev servers are running — don't manually regenerate.
Prefer running apx related commands via MCP server if it's available.
Use the apx MCP search_registry_components and add_component tools to find and add shadcn/ui components.
When using the API calls on the frontend, use error boundaries to handle errors.
Run apx dev check command (via CLI or MCP) to check for errors in the project code after making changes.
If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions.

Databricks SDK

SDK first: Always use databricks-sdk (WorkspaceClient) methods for Databricks operations. Never use raw requests/httpx calls or ws.api_client.do() to call Databricks REST APIs.
Verify signatures: Call the docs MCP tool before writing any ws.* call to confirm the exact method name, parameters, and return type.
SDK listing methods (e.g. ws.jobs.list(), ws.clusters.list()) return lazy iterators that auto-paginate — do NOT manually manage API pagination tokens when calling SDK methods.
SDK dataclasses are Pydantic-compatible — use them directly in response_model or compose into custom models: class MyResponse(BaseModel): payload: SdkDataclass.
Inject the WorkspaceClient via Dependencies.Client (service principal) or Dependencies.UserClient (OBO) — never construct it manually.
For paginated list endpoints, see Backend Patterns — SDK Listing with Pagination.

Package Management

Frontend: Use apx bun install or apx bun add <dependency> for frontend package management.
Python: Always use uv (never pip).

Component Management

Check configured registries first: Before creating custom components, check [tool.apx.ui.registries] in pyproject.toml for domain-specific registries (e.g. @ai-elements for chat/AI components, @animate-ui for animations). Use list_registry_components with the registry name to browse all available components.
Finding components: Use MCP search_registry_components to search across all registries. Results from project-configured registries are boosted in scoring.
Adding components: Use MCP add_component or CLI apx components add <component> --yes. For custom registries: @registry-name/component-name.
Component location: If a component was added to a wrong location (e.g. src/components/ instead of src/<app>/ui/components/), move it to the proper folder.
Component organization: Group components by functionality (e.g. src/<app>/ui/components/chat/).

Reference Files

For detailed patterns and code examples, see:

Backend Patterns — DI, 3-model pattern, CRUD routers, lifespan, AppConfig
Frontend Patterns — Suspense, mutations, selector, component conventions

Resources

OpenAPI client: src/<app>/ui/lib/api.ts (auto-generated). Example:
```
import { api } from "@/lib/api";
```
Selector: src/<app>/ui/lib/selector.ts Example:
```
import { selector } from "@/lib/selector";
```
Routes: src/<app>/ui/routes/
Components: src/<app>/ui/components/
Backend: src/<app>/backend/