App skills

databricks-skills/build-databricks-app/SKILL.md

@@ -0,0 +1,241 @@
+# Build Databricks APX Application
+
+Build full-stack Databricks applications using APX framework (FastAPI + React).
+
+## Trigger Conditions
+
+**Invoke when user requests**:
+- "Databricks app" or "Databricks application"
+- Full-stack app for Databricks without specifying framework
+- Mentions APX framework
+
+**Do NOT invoke if user specifies**: Streamlit, Dash, Node.js, Shiny, Gradio, Flask, or other frameworks.
+
+## Prerequisites Check
+
+Option A)
+Repository configured for use with APX.
+1.. Verify APX MCP available: `mcp-cli tools | grep apx`
+2. Verify shadcn MCP available: `mcp-cli tools | grep shadcn`
+3. Confirm APX project (check `pyproject.toml`)
+
+Option B)
+Install APX
+1. Verify uv available or prompt for install. On Mac, suggest: `brew install uv`.
+2. Verify bun available or prompt for install. On Mac, suggest: 
+```
+brew tap oven-sh/bun
+brew install bun
+```
+3. Verify git available or prompt for install.
+4. Run APX setup commands:
+```
+uvx --from git+https://github.com/databricks-solutions/apx.git apx init
+```
+
+
+## Workflow Overview
+
+Total time: 55-70 minutes
+
+1. **Initialize** (5 min) - Start servers, create todos
+2. **Backend** (15-20 min) - Models + routes with mock data
+3. **Frontend** (20-25 min) - Components + pages
+4. **Test** (5-10 min) - Type check + manual verification
+5. **Document** (10 min) - README + code structure guide
+
+## Phase 1: Initialize
+
+```bash
+# Start APX development server
+mcp-cli call apx/start '{}'
+mcp-cli call apx/status '{}'
+```
+
+Create TodoWrite with tasks:
+- Start servers ✓
+- Design models
+- Create API routes
+- Add UI components
+- Create pages
+- Test & document
+
+## Phase 2: Backend Development
+
+### Create Pydantic Models
+
+In `src/{app_name}/backend/models.py`:
+
+**Follow 3-model pattern**:
+- `EntityIn` - Input validation
+- `EntityOut` - Complete output with computed fields
+- `EntityListOut` - Performance-optimized summary
+
+**See [backend-patterns.md](backend-patterns.md) for complete code templates.**
+
+### Create API Routes
+
+In `src/{app_name}/backend/router.py`:
+
+**Critical requirements**:
+- Always include `response_model` (enables OpenAPI generation)
+- Always include `operation_id` (becomes frontend hook name)
+- Use naming pattern: `listX`, `getX`, `createX`, `updateX`, `deleteX`
+- Initialize 3-4 mock data samples for testing
+
+**See [backend-patterns.md](backend-patterns.md) for complete CRUD templates.**
+
+### Type Check
+
+```bash
+mcp-cli call apx/dev_check '{}'
+```
+
+Fix any Python type errors reported by basedpyright.
+
+## Phase 3: Frontend Development
+
+**Wait 5-10 seconds** after backend changes for OpenAPI client regeneration.
+
+### Add UI Components
+
+```bash
+# Get shadcn add command
+mcp-cli call shadcn/get_add_command_for_items '{
+  "items": ["@shadcn/button", "@shadcn/card", "@shadcn/table",
+            "@shadcn/badge", "@shadcn/select", "@shadcn/skeleton"]
+}'
+```
+
+Run the command from project root with `--yes` flag.
+
+### Create Pages
+
+**List page**: `src/{app_name}/ui/routes/_sidebar/{entity}.tsx`
+- Table view with all entities
+- Suspense boundaries with skeleton fallback
+- Formatted data (currency, dates, status colors)
+
+**Detail page**: `src/{app_name}/ui/routes/_sidebar/{entity}.$id.tsx`
+- Complete entity view with cards
+- Update/delete mutations
+- Back navigation
+
+**See [frontend-patterns.md](frontend-patterns.md) for complete page templates.**
+
+### Update Navigation
+
+In `src/{app_name}/ui/routes/_sidebar/route.tsx`, add new item to `navItems` array.
+
+## Phase 4: Testing
+
+```bash
+# Type check both backend and frontend
+mcp-cli call apx/dev_check '{}'
+
+# Test API endpoints
+curl http://localhost:8000/api/{entities} | jq .
+curl http://localhost:8000/api/{entities}/{id} | jq .
+
+# Get frontend URL
+mcp-cli call apx/get_frontend_url '{}'
+```
+
+Manually verify in browser:
+- List page displays data
+- Detail page shows complete info
+- Mutations work (update, delete)
+- Loading states work (skeletons)
+- Browser console errors are automatically captured in APX dev logs
+
+## Phase 5: Deployment & Monitoring
+
+### Deploy to Databricks
+
+Use DABs to deploy your APX application to Databricks. See the `dabs-writer` skill for complete deployment guidance.
+
+### Monitor Application Logs
+
+**Automated log checking with APX MCP:**
+
+The APX MCP server can automatically check deployed application logs. Simply ask:
+"Please check the deployed app logs for <app-name>"
+
+
+The APX MCP will retrieve logs and identify issues automatically, including:
+- Deployment status and errors
+- Runtime exceptions and stack traces
+- Both `[SYSTEM]` (deployment) and `[APP]` (application) logs
+- Browser console errors (now included in APX dev logs)
+
+**Manual log checking (reference):**
+
+For direct CLI access:
+```bash
+databricks apps logs <app-name> --profile <profile-name>
+```
+
+**Key patterns to look for:**
+- ✅ `Deployment successful` - App deployed correctly
+- ✅ `App started successfully` - Application is running
+- ❌ `Error:` - Check stack traces for issues
+
+## Phase 6: Documentation
+
+Create two markdown files:
+
+**README.md**:
+- Features overview
+- Technology stack
+- How app was created (AI tools + MCP servers used)
+- Application architecture
+- Getting started instructions
+- API documentation
+- Development workflow
+
+**CODE_STRUCTURE.md**:
+- Directory structure explanation
+- Backend structure (models, routes, patterns)
+- Frontend structure (routes, components, hooks)
+- Auto-generated files warnings
+- Guide for adding new features
+- Best practices
+- Common patterns
+- Troubleshooting guide
+
+## Key Patterns
+
+### Backend
+- **3-model pattern**: Separate In, Out, and ListOut models
+- **operation_id naming**: `listEntities` → `useListEntities()`
+- **Type hints everywhere**: Enable validation and IDE support
+
+### Frontend
+- **Suspense hooks**: `useXSuspense(selector())`
+- **Suspense boundaries**: Always provide skeleton fallback
+- **Formatters**: Currency, dates, status colors
+- **Never edit**: `lib/api.ts` or `types/routeTree.gen.ts`
+
+## Success Criteria
+
+- [ ] Type checking passes (`apx dev check` succeeds)
+- [ ] API endpoints return correct data (curl verification)
+- [ ] Frontend displays and mutates data correctly
+- [ ] Loading states work (skeletons display)
+- [ ] Documentation complete
+
+## Common Issues
+
+**Deployed app not working**: Ask to check deployed app logs (APX MCP will automatically retrieve and analyze them) or manually use `databricks apps logs <app-name>`
+**Python type errors**: Use explicit casting for dict access, check Optional fields
+**TypeScript errors**: Wait for OpenAPI regen, verify hook names match operation_ids
+**OpenAPI not updating**: Check watcher status with `apx dev status`, restart if needed
+**Components not added**: Run shadcn from project root with `--yes` flag
+
+## Reference Materials
+
+- **[backend-patterns.md](backend-patterns.md)** - Complete backend code templates
+- **[frontend-patterns.md](frontend-patterns.md)** - Complete frontend page templates
+- **[best-practices.md](best-practices.md)** - Best practices, anti-patterns, debugging
+
+Read these files only when actively writing that type of code or debugging issues.