Fix AppKit template documentation for LLMs #4243
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
LLMs were adding query schemas but not running npm run typegen, causing TypeScript errors like "query key not assignable to type". Made Step 3 explicit: run typegen after any schema change. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
keugenek
requested review from
a team,
andrewnester,
anton-107,
denik,
lennartkats-db,
pietern and
shreyas-goenka
as code owners
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Collaborator
|
Commit: bd4e486
26 interesting tests: 15 RECOVERED, 10 KNOWN, 1 SKIP
Top 46 slowest tests (at least 2 minutes):
|
The hook's return type doesn't infer from QueryRegistry, so data is typed as {}.
Without manual casting, TypeScript errors like "Property 'map' does not exist" occur.
TODO: File SDK improvement PR to fix useAnalyticsQuery type inference
from QueryRegistry so casting isn't needed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
| **To refresh TypeScript types after adding queries:** | ||
| - Run `npm run typegen` OR run `npm run dev` - both auto-generate type definitions in `client/src/appKitTypes.d.ts` | ||
| - DO NOT manually edit `appKitTypes.d.ts` | ||
| **⚠️ CRITICAL: Always run `npm run typegen` after modifying `config/queries/schema.ts`** |
Contributor
There was a problem hiding this comment.
The schema.ts file doesn't exist anymore, only the appKitTypes file
fjakobs
requested changes
Jan 12, 2026
| - Conditional rendering based on data values | ||
| - Data that needs transformation before display | ||
|
|
||
| **⚠️ CRITICAL: Always cast data to the correct type** |
Contributor
There was a problem hiding this comment.
Casting should generally not be required. This needs to be fixed in AppKit
There was a problem hiding this comment.
This is a bug, I will check. The data from the hooks is already cast.
The most critical workflow steps were only in template docs, which agents sometimes skip. Adding to MCP guidance ensures agents see this during databricks_discover call: - npm run typegen required after schema changes - data casting required for useAnalyticsQuery - chart components don't accept children Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
keugenek
force-pushed
the
fix/appkit-docs-for-llms
branch
from
2aab02a to
f5f1230
Compare
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
AppKit SDK will fix type inference from QueryRegistry, making manual casting unnecessary. Removed workaround documentation per PR review feedback. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
keugenek
force-pushed
the
fix/appkit-docs-for-llms
branch
from
c5ec8c8 to
88ff134
Compare
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
AppKit-specific guidance now lives in skills/apps/appkit/. target_apps.tmpl focuses on validation, deployment, and operational commands only. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
keugenek
force-pushed
the
fix/appkit-docs-for-llms
branch
from
88ff134 to
5bc4642
Compare
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Move AppKit documentation from appkit repo llms.txt to CLI skills. This establishes CLI as the single source of truth for agent guidance. Includes: - SKILL.md: Overview, hard rules, quick start - appkit-backend.md: Server, analytics, plugins, caching - appkit-frontend.md: Charts, hooks, UI components, SSE - appkit-scaffolding.md: Project setup, type generation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
keugenek
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fixes critical documentation issues causing ~90% build failure rate in LLM-generated AppKit apps.
Changes:
npm run typegena required explicit step after schema changesuseAnalyticsQuerydata must be cast manuallytarget_apps.tmplso agents see it duringdatabricks_discoverRoot causes addressed:
<BarChart><Bar .../></BarChart>→ TypeScript errors (charts don't accept children)npm run typegen→ "not assignable to type" errorsdata?.map()without casting → "Property 'map' does not exist on type '{}'" errorsTest plan
Files changed
templates/appkit/template/{{.project_name}}/CLAUDE.md- typegen as Step 3templates/appkit/template/{{.project_name}}/docs/frontend.md- chart children warningtemplates/appkit/template/{{.project_name}}/docs/appkit-sdk.md- data casting guidancelib/prompts/target_apps.tmpl- AppKit workflow in MCP guidance🤖 Generated with Claude Code