feat(sdk): add readme, agents.md, and claude skill with docs links to app templates#1303
Open
ryanbonial wants to merge 2 commits into
Open
feat(sdk): add readme, agents.md, and claude skill with docs links to app templates#1303ryanbonial wants to merge 2 commits into
ryanbonial wants to merge 2 commits into
Conversation
Contributor
📦 Bundle Stats —
|
| Metric | Value | vs main (8985b42) |
|---|---|---|
| Internal (raw) | 2.1 KB | - |
| Internal (gzip) | 799 B | - |
| Bundled (raw) | 11.13 MB | - |
| Bundled (gzip) | 2.10 MB | - |
| Import time | 884ms | -4ms, -0.4% |
bin:sanity
| Metric | Value | vs main (8985b42) |
|---|---|---|
| Internal (raw) | 782 B | - |
| Internal (gzip) | 423 B | - |
| Bundled (raw) | 9.87 MB | - |
| Bundled (gzip) | 1.77 MB | - |
| Import time | 1.96s | -57ms, -2.8% |
🗺️ View treemap · Artifacts
Details
- Import time regressions over 10% are flagged with
⚠️ - Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.
📦 Bundle Stats — @sanity/cli-core
Compared against main (8985b42f)
| Metric | Value | vs main (8985b42) |
|---|---|---|
| Internal (raw) | 98.2 KB | - |
| Internal (gzip) | 23.3 KB | - |
| Bundled (raw) | 21.70 MB | - |
| Bundled (gzip) | 3.45 MB | - |
| Import time | 784ms | -13ms, -1.6% |
🗺️ View treemap · Artifacts
Details
- Import time regressions over 10% are flagged with
⚠️ - Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.
📦 Bundle Stats — create-sanity
Compared against main (8985b42f)
| Metric | Value | vs main (8985b42) |
|---|---|---|
| Internal (raw) | 908 B | - |
| Internal (gzip) | 483 B | - |
| Bundled (raw) | 931 B | - |
| Bundled (gzip) | 491 B | - |
| Import time | ❌ ChildProcess denied: node | - |
Details
- Import time regressions over 10% are flagged with
⚠️ - Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.
Contributor
Coverage DeltaNo covered files changed in this PR. Overall Coverage
|
cngonzalez
approved these changes
Jun 16, 2026
cngonzalez
left a comment
cngonzalez
left a comment
Member
There was a problem hiding this comment.
One nit about suspense, otherwise LGTM
| <SanityApp config={sanityConfigs}> | ||
| <YourComponent /> | ||
| </SanityApp>`}</pre> | ||
| const {data} = useDocuments({documentType: 'yourType'})`}</pre> |
Member
There was a problem hiding this comment.
This might be a good opportunity to enforce / encourage Suspense usage (we've been getting dinged on it a bit in AILF runs. I know it's mentioned in the skill too but might be nice!)
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
2 participants
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.
Description
Running
npx sanity init --template app-quickstart(orapp-sanity-ui) currently scaffolds a bare hello-world app with no README, no agent guidance, and an example component that gives no pointers to the App SDK docs. Users, and the LLM agents many of them start these apps with, are left to guess what to do next.This PR adds lightweight orientation to both app templates without adding boilerplate code:
README.mdin each template root: what an SDK app is, thedev/build/deploycommands, where project and dataset config lives, and docs links (with?utm_source=readme, matching the existing studio template READMEs).AGENTS.mdin each template root: guidance for coding agents picking up a fresh scaffold. Covers what the project is, key files, commands, the SDK concepts agents commonly get wrong (document handles, Suspense, hooks insideSanityApp), and a pointer to the Sanity MCP server'sget_sanity_rulestool with theapp-sdkrule..claude/skills/sanity-app-sdk/SKILL.mdin each template: an on-demand skill with the hook-picking guide, document handle and editing patterns with code examples, and docs links. The sanity-ui variant also covers Sanity UI usage.ExampleComponentin both templates: replaces the generic "create a component" hint with a concrete next step (useDocuments) and links to the App SDK docs, the API reference, and the SDK Explorer. Also fixes a stalesrc/App.tsx|jsxmention (app templates are TypeScript-only).The docs are careful to describe the dev flow accurately:
npm run devstarts a local server, but the app only renders inside the Sanity Dashboard. The CLI prints a Dashboard URL, and viewing it requires a signed-in Sanity account.Solves SDK-1744: https://linear.app/sanity/issue/SDK-1744/improve-sdk-app-templates-with-docs-links-readme-and-agent-guidance
What to review
packages/@sanity/cli/templates/app-quickstart/andpackages/@sanity/cli/templates/app-sanity-ui/. No CLI code changes:bootstrapLocalTemplate.tscopies template directories verbatim (including dotfolders), and the package's npmfilesfield already ships./templates.SANITY_APP_env prefix, Dashboard dev flow) and the SDK guidance against@sanity/sdk-react(handles, Suspense,useEditDocument).pnpm build:cli, then runsanity init --template app-quickstartand confirm the README, AGENTS.md, and.claude/folder land in the output directory.Testing
No new automated tests. The added files are static template content copied verbatim during scaffolding; the init unit tests mock
bootstrapTemplateand the e2e tests assert specific files exist, so nothing breaks. The factual claims in the docs were verified against the CLI source (dev server flow, generatedpackage.jsonscripts,sanity.cli.tsgeneration, Vite env prefix) and the SDK source (hook signatures and Suspense behavior), and all linked docs URLs were checked to resolve.Note
Low Risk
Static template and documentation-only changes; no runtime or CLI behavior modifications.
Overview
Adds onboarding and agent guidance to the
app-quickstartandapp-sanity-uiCLI scaffolds so new SDK apps ship with orientation instead of a bare hello-world.Each template now includes a README (commands, config locations, docs links with
?utm_source=readme), AGENTS.md (project shape, dev/Dashboard flow, common SDK pitfalls like handles, Suspense, anduseEditDocument), and a.claude/skills/sanity-app-sdk/SKILL.mdhook/editing cheat sheet (Sanity UI notes on the UI template). The example components steer users towarduseDocumentsas the next step, add links to App SDK docs, API reference, and SDK Explorer, and drop the staleApp.tsx|jsxwording.A changeset records a minor bump for
@sanity/cli; template files are copied verbatim at init—no bootstrap logic changes.Reviewed by Cursor Bugbot for commit 40cde12. Bugbot is set up for automated code reviews on this repo. Configure here.