| name | sanity-app-sdk |
| description | Build features with the Sanity App SDK (@sanity/sdk-react) and Sanity UI. Use when adding components, fetching or editing Sanity content, or working with hooks like useDocuments, useDocument, useDocumentProjection, useEditDocument, or useQuery. |
Sanity App SDK
Get the maintained guide first
If the Sanity MCP server is configured, call its get_sanity_rules tool with the app-sdk rule before writing SDK code. That rule is maintained by Sanity, is more detailed, and supersedes the notes below. The notes below are a fallback for when MCP is not available.
Picking a hook
useDocuments / usePaginatedDocuments: lists of documents. Returns document handles, not full documents.useDocumentProjection: read specific fields from a handle, for display.useDocument plus useEditDocument: read and write a single document in real time.useQuery: raw GROQ. Use sparingly; prefer handles plus projections.
Document handles
Fetch handles first, then spread them into other hooks:
const {data} = useDocuments({documentType: 'article'})
const {data: fields} = useDocumentProjection({...handle, projection: '{title}'})
Use documentId as the React key when rendering lists, never the array index.
Suspense
Data hooks suspend while loading. Wrap every data-fetching component in <Suspense> with a fallback, keep one fetching hook per component, and always pass a fallback to SanityApp. All SDK hooks must be used inside SanityApp.
Editing
Write through useEditDocument on change so content stays in sync with the Content Lake:
const {data: title} = useDocument({...handle, path: 'title'})
const editTitle = useEditDocument({...handle, path: 'title'})
Do not hold document field values in useState and save on submit. That pattern goes stale and loses concurrent edits.
Sanity UI
This app wraps everything in Sanity UI's ThemeProvider (see src/SanityUI.tsx, built with buildTheme()). Build UI with Sanity UI primitives like Card, Stack, Flex, Text, and Button. See https://www.sanity.io/docs/app-sdk/sanity-ui-sdk and https://www.sanity.io/ui.
Documentation
Fetch these for current detail rather than relying on the notes above:
