docs: committed .appkit/ type cache and warehouse-less deploys - #503
Merged
Conversation
Reflect the typegen cache relocation in the docs: - type-generation.md: add a "Type cache" section (cache now lives in the committed .appkit/ dir, not node_modules; what to commit; deterministic serialization) and a "Deploying without warehouse access" subsection covering the rollout ordering (seed + commit .appkit/ while the warehouse is reachable, then cut access) and the bootstrap-vs-drift failure messages. Update the --wait section to describe hit-skips-warehouse / miss-attempts / unresolved-miss-fails semantics. - project-setup.md: add .appkit/ to the canonical layout as a committed artifact (do not gitignore). - app-management.mdx: deploy-guide admonition that a warehouse-less deploy needs a committed .appkit/ covering every query. Co-authored-by: Isaac Signed-off-by: Atila Fassina <atila@fassina.eu>
atilafassina
marked this pull request as ready for review
July 31, 2026 12:57
atilafassina
requested review from
Copilot,
ditadi and
pkosiec
and removed request for
a team
July 31, 2026 12:57
Contributor
There was a problem hiding this comment.
Pull request overview
Updates AppKit documentation to reflect the relocated, committed typegen cache under .appkit/ (from PR #502) and to document the “warehouse-less deploy” workflow enabled by that change.
Changes:
- Documented the new committed
.appkit/type cache location (and what remains ephemeral undernode_modules/.databricks/appkit/). - Added guidance for deploying/building in CI/CD without SQL warehouse access, including required rollout ordering and failure behavior.
- Updated project layout and deploy docs to reference
.appkit/and link to the detailed typegen guidance.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/docs/development/type-generation.md | Adds a “Type cache” section and details blocking mode cache-hit/miss behavior plus warehouse-less deploy guidance. |
| docs/docs/development/project-setup.md | Updates the canonical project layout to include committed .appkit/. |
| docs/docs/app-management.mdx | Adds an admonition warning that warehouse-less deploys require a fully-populated committed .appkit/ cache. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+102
to
+105
| This imposes a rollout ordering: **produce and commit `.appkit/` while the warehouse is still reachable, then remove warehouse access.** A build that runs after warehouse access is gone with an uninitialized or incomplete cache fails loudly (never silently degrades to `unknown`), and the error message tells you which case you hit: | ||
|
|
||
| - **Uninitialized cache** (no `.appkit/` yet) — run `generate-types --wait` against a warehouse and commit `.appkit/`. | ||
| - **Drifted cache** (a query changed since the cache was built) — regenerate the affected query against a warehouse and commit the updated `.appkit/`. |
Align the warehouse-less deploy failure bullets with the strings the
build actually prints ('No committed type cache found' vs 'The committed
.appkit/ cache is missing or stale') so they are greppable in CI logs,
and broaden the drift case to cover added/missing queries, not just
changed ones.
Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>
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
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.
What
Documentation for the typegen cache relocation in #502 (stacked on top of it; base =
move-typegen). The code moves the type cache fromnode_modules/to a committed.appkit/directory and changes deploy semantics; the docs didn't reflect any of that.Changes
development/type-generation.md— new Type cache section: the cache now lives in the committed.appkit/dir (types-cache.json+serving-types-cache.json), must be checked into git (not gitignored), ephemeral state stays undernode_modules/.databricks/appkit/, and serialization is deterministic. New Deploying without warehouse access subsection: the rollout ordering (produce + commit.appkit/while the warehouse is reachable, then remove access) and the bootstrap-vs-drift failure messages. Updated the--waitsection to describe hit-skips-warehouse / miss-attempts / unresolved-miss-fails-loud.development/project-setup.md—.appkit/added to the canonical project layout as a committed artifact.app-management.mdx— deploy-guide admonition that a warehouse-less deploy needs a committed.appkit/covering every query, linking to the type-generation detail.Verification
pnpm docs:build— ✅ both bundles compile, 230 docs processed, no broken internal links (the new cross-references resolve).pnpm docs:check— ✅ 24 files, no fixes.Stacking
Base is
move-typegen(#502), so this PR's diff shows only the doc changes. Merge #502 first; this retargets tomainautomatically once #502 lands.This pull request and its description were written by Isaac.