Nuxt + Sanity Integration Best Practices
Best-practices guide for the @nuxtjs/sanity module (Nuxt 3). Covers module
setup, composables, SSR data fetching, image handling, Portable Text, visual
editing, TypeScript, and Nitro server routes.
Also load the nuxt skill for Nuxt core patterns and sanity-best-practices
for GROQ query optimization and schema design. This skill covers the
integration layer only.
ROUTING: Which rule file to load
IF setting up the module or configuring nuxt.config.ts:
→ Read rules/core-module-setup.md
IF using useSanityQuery, useLazySanityQuery, or useSanity composables:
→ Read rules/core-composables.md
IF writing Nitro server routes that query Sanity:
→ Read rules/core-server-routes.md
IF working with the SanityImage component or useSanityImage():
→ Read rules/features-sanity-image.md
IF rendering Portable Text with SanityContent:
→ Read rules/features-sanity-content.md
IF implementing visual editing, live preview, stega, or the Presentation tool:
→ Read rules/features-visual-editing.md
IF experiencing stale data, cache misses, or reactive query bugs:
→ Read rules/perf-query-keys-and-caching.md
IF debugging CORS errors, auth token issues, or hydration mismatches:
→ Read rules/debug-common-errors.md
IF generating a dynamic sitemap from Sanity routes (works, case studies, etc.):
→ Read rules/features-sitemap.md
Rule index
| Topic |
Description |
File |
| Sections overview |
Categories and reading order |
rules/_sections.md |
| Module setup |
Installation, nuxt.config.ts options, env vars |
rules/core-module-setup.md |
| Composables |
useSanityQuery, useLazySanityQuery, useSanity usage |
rules/core-composables.md |
| Server routes |
Nitro server routes with useSanity, validateSanityQuery |
rules/core-server-routes.md |
| SanityImage |
SanityImage component, useSanityImage(), @nuxt/image integration |
rules/features-sanity-image.md |
| SanityContent |
Portable Text rendering, custom components |
rules/features-sanity-content.md |
| Visual editing |
Stega, live preview, Presentation tool, draft mode |
rules/features-visual-editing.md |
| Caching |
Query key stability, reactive params, cache invalidation |
rules/perf-query-keys-and-caching.md |
| Debug |
CORS, auth tokens, hydration errors, common pitfalls |
rules/debug-common-errors.md |
| Sitemap |
Dynamic sitemap sources, defineSitemapEventHandler, stegaClean on slugs |
rules/features-sitemap.md |
Rule categories by priority
| Priority |
Category |
Impact |
Prefix |
| 1 |
Module setup & composables |
CRITICAL |
core- |
| 2 |
Server routes |
HIGH |
core- |
| 3 |
Visual editing |
HIGH |
features- |
| 4 |
Image & Portable Text |
HIGH |
features- |
| 5 |
Caching & performance |
MEDIUM-HIGH |
perf- |
| 6 |
Debug |
MEDIUM |
debug- |
Coverage and maintenance
1---2name: nuxt-sanity3description: @nuxtjs/sanity module integration best practices for Nuxt 3 apps connected to Sanity CMS. Covers useSanityQuery, useLazySanityQuery, useSanity, SanityImage, SanityContent (Portable Text), visual editing / live preview with stega, TypeScript typegen, named clients, and Nitro server routes. Use when the user mentions @nuxtjs/sanity, nuxt-sanity, useSanityQuery, SanityImage in Nuxt, or is building a Nuxt app that fetches data from Sanity.4---5
6# Nuxt + Sanity Integration Best Practices
7
8Best-practices guide for the `@nuxtjs/sanity` module (Nuxt 3). Covers module
9setup, composables, SSR data fetching, image handling, Portable Text, visual
10editing, TypeScript, and Nitro server routes.
11
12> Also load the `nuxt` skill for Nuxt core patterns and `sanity-best-practices`
13> for GROQ query optimization and schema design. This skill covers the
14> integration layer only.
15
16## ROUTING: Which rule file to load
17
18**IF setting up the module or configuring nuxt.config.ts:**
19→ Read `rules/core-module-setup.md`
20
21**IF using useSanityQuery, useLazySanityQuery, or useSanity composables:**
22→ Read `rules/core-composables.md`
23
24**IF writing Nitro server routes that query Sanity:**
25→ Read `rules/core-server-routes.md`
26
27**IF working with the SanityImage component or useSanityImage():**
28→ Read `rules/features-sanity-image.md`
29
30**IF rendering Portable Text with SanityContent:**
31→ Read `rules/features-sanity-content.md`
32
33**IF implementing visual editing, live preview, stega, or the Presentation tool:**
34→ Read `rules/features-visual-editing.md`
35
36**IF experiencing stale data, cache misses, or reactive query bugs:**
37→ Read `rules/perf-query-keys-and-caching.md`
38
39**IF debugging CORS errors, auth token issues, or hydration mismatches:**
40→ Read `rules/debug-common-errors.md`
41
42**IF generating a dynamic sitemap from Sanity routes (works, case studies, etc.):**
43→ Read `rules/features-sitemap.md`
44
45## Rule index
46
47| Topic | Description | File |
48|-------|-------------|------|
49| Sections overview | Categories and reading order | [rules/_sections.md](rules/_sections.md) |
50| Module setup | Installation, nuxt.config.ts options, env vars | [rules/core-module-setup.md](rules/core-module-setup.md) |
51| Composables | useSanityQuery, useLazySanityQuery, useSanity usage | [rules/core-composables.md](rules/core-composables.md) |
52| Server routes | Nitro server routes with useSanity, validateSanityQuery | [rules/core-server-routes.md](rules/core-server-routes.md) |
53| SanityImage | SanityImage component, useSanityImage(), @nuxt/image integration | [rules/features-sanity-image.md](rules/features-sanity-image.md) |
54| SanityContent | Portable Text rendering, custom components | [rules/features-sanity-content.md](rules/features-sanity-content.md) |
55| Visual editing | Stega, live preview, Presentation tool, draft mode | [rules/features-visual-editing.md](rules/features-visual-editing.md) |
56| Caching | Query key stability, reactive params, cache invalidation | [rules/perf-query-keys-and-caching.md](rules/perf-query-keys-and-caching.md) |
57| Debug | CORS, auth tokens, hydration errors, common pitfalls | [rules/debug-common-errors.md](rules/debug-common-errors.md) |
58| Sitemap | Dynamic sitemap sources, defineSitemapEventHandler, stegaClean on slugs | [rules/features-sitemap.md](rules/features-sitemap.md) |
59
60## Rule categories by priority
61
62| Priority | Category | Impact | Prefix |
63|----------|----------|--------|--------|
64| 1 | Module setup & composables | CRITICAL | `core-` |
65| 2 | Server routes | HIGH | `core-` |
66| 3 | Visual editing | HIGH | `features-` |
67| 4 | Image & Portable Text | HIGH | `features-` |
68| 5 | Caching & performance | MEDIUM-HIGH | `perf-` |
69| 6 | Debug | MEDIUM | `debug-` |
70
71## Coverage and maintenance
72
73- Coverage map: `rules/_coverage-map.md`
74- Module source: https://github.com/nuxt-modules/sanity
75- Update when `@nuxtjs/sanity` releases a new major version or visual editing APIs change.
majiayu000