Next Sanity Starter

Setup

Requirements

Node.js 20+ (22 recommended; CI tests 20 and 22), pnpm 10 (pinned in root packageManager), a Sanity project with project id. Optional: Mux tokens for video uploads; Netlify (or any host) for deploy — netlify.toml is included.

Fork or clone

• Fork the repo on GitHub (or clone upstream), then git clone your fork locally.
• Pick an i18n branch before you customize: main = field-level translations in one document; variant/document-level = separate document per language. PR #62 compares both — choose once, then build on that branch.
• Mono-repo layout: web/ (Next.js), studio/ (Sanity), packages/* (shared resolver, strip-readmes helper).

Install

• From repo root: pnpm install (workspaces: web, studio, packages).
• Copy env templates:
  • web/.env.example → web/.env.local
  • studio/.env.example → studio/.env
• Set SANITY_STUDIO_PROJECT_ID in both files (same Sanity project). That is the only required variable for local dev; everything else has sensible defaults.

Datasets (recommended)

• Create a development dataset in Sanity (UI or CLI) so local edits never touch live content — resolver prefers development locally and in preview.
• Or pin SANITY_STUDIO_DATASET=production (and optionally NEXT_PUBLIC_SANITY_DATASET on web) to skip dev/prod splitting.
• Optional: SANITY_STUDIO_DEPLOYMENT_TARGET per deploy environment (staging, production, …). See section 9 for resolver rules.

First run

• pnpm dev — Studio (http://localhost:3333) and web (http://localhost:3000) in parallel.
• Or separately: pnpm studio:dev, pnpm web:dev (web uses next dev --webpack by default on Next 16.2).
• In Studio: Settings → Site languages — publish (defaults en + de on first create). Create a page with a unique slug. Open http://localhost:3000/<slug> (default locale unprefixed) or http://localhost:3000/de/<slug>.

Presentation / draft (optional for day one)

• Add SANITY_API_READ_TOKEN to web/.env.local for draft mode and Visual Editing.
• Set SANITY_STUDIO_PREVIEW_ORIGIN=http://localhost:3000 in studio/.env (match host exactly — not mixing 127.0.0.1 and localhost).

Ship your fork

• Documentation lives in per-folder READMEs while you learn; remove them in bulk when the fork is yours: pnpm strip-readmes (@repo/strip-readmes).
• Regenerate types after schema changes: pnpm studio:generate.
• Deploy web (Netlify or other) with env from section 9; deploy Studio with pnpm studio:deploy (sets production dataset target on deploy script).
• Configure Sanity Revalidate webhook → https://<your-site>/api/revalidate with SANITY_REVALIDATE_SECRET.

Scripts (root)

• pnpm build · pnpm lint · pnpm format · pnpm typecheck · pnpm studio:sync-prod-to-dev (manual prod → dev dataset clone).

Tooling, CI, deploy

• pnpm workspaces — web, studio, packages/*.
• Biome — root config; Studio 2-space override, rest tabs. Husky: pre-commit format, pre-push format + typecheck.
• GitHub Actions — verify (Biome + diff, TS Node 20/22), schema-typegen (extract + generate + diff), build-web, build-studio; concurrency cancel.
• Dependabot — weekly npm; Sanity plugins grouped.
• Node 20 minimum, 22 recommended; pnpm 10 pinned.
• Web dev: pnpm web:dev runs next dev --webpack (Turbopack optional; avoids panics on some Next 16.2 setups).
• Studio deploy: pnpm studio:deploy sets SANITY_STUDIO_DEPLOYMENT_TARGET=production.
• pnpm strip-readmes — bulk-remove per-folder READMEs when shipping a fork.

Key environment variables

• SANITY_STUDIO_PROJECT_ID — required (both apps).
• SANITY_API_READ_TOKEN — draft + server draft reads (optional locally, needed for VE).
• SANITY_REVALIDATE_SECRET — required in production for webhook.
• NEXT_PUBLIC_SITE_URL — required in prod (sitemap, robots, metadata base).
• SANITY_STUDIO_PREVIEW_ORIGIN — Studio Presentation iframe origin.
• SANITY_STUDIO_DEPLOYMENT_TARGET — dataset preference / custom dataset name per deploy env.
• SANITY_STUDIO_DATASET / NEXT_PUBLIC_SANITY_DATASET — hard pin.
• Mux — SANITY_STUDIO_MUX_TOKEN_ID / _SECRET in studio/.env.

Workspace Features

Dataset detection (@repo/sanity-dataset-resolve)

Both web and Studio resolve the Content Lake dataset through the same package — not NODE_ENV (local next start still prefers development when appropriate).

Resolution order:

• Explicit pin wins — SANITY_STUDIO_DATASET or NEXT_PUBLIC_SANITY_DATASET skips all heuristics.
• SANITY_STUDIO_DEPLOYMENT_TARGET sets preference order:
  • production → try production first, fall back to development.
  • development / preview / unset → try development first, fall back to production.
  • Custom name (e.g. staging) → that dataset first, then the dev/prod pair in deployment order.
• Canonical names overridable via SANITY_STUDIO_DATASET_DEVELOPMENT / _PRODUCTION (defaults: development, production).
• Existence check — with project id + token (SANITY_STUDIO_DATASET_RESOLVER_TOKEN or SANITY_API_READ_TOKEN), the Management API lists datasets; otherwise HTTP probe on the Data API. Avoids requesting a dataset that does not exist.
• Host inference — on Vercel (VERCEL_ENV=production) or Netlify (CONTEXT=production), prefer production first when target is unset.

Where consumed: web/sanity/sanityEnv.ts, web/sanity/resolveStudioDataset.ts, studio/config/sync/studioDataset.ts. Image URLs use the same projectId + dataset as client.ts.

Operational notes:

• No in-UI dataset switch — dev server or deploy env picks the dataset.
• Recommended: create a development dataset for local iteration; or pin SANITY_STUDIO_DATASET=production to skip splitting.
• Prod → dev sync is manual only: pnpm studio:sync-prod-to-dev exports production to a tarball, imports into development with --replace. Never automatic (destructive for dev-only content). Dev server prints a reminder; pass --yes for CI.

Netlify: build.ignore is dataset-aware — commits that only touch studio/ skip rebuilding the web app.

Data access & caching

Two fetch paths:

• fetchSanityData.ts — wraps sanityFetch from defineLive (live.ts). Use on app routes that need Draft Mode, Presentation, and Stega. SanityLive mounts only when a read token is present or draft mode is active.
• cachedSanityQuery.ts — client.fetch + unstable_cache + cache tags. Published-only paths: sitemap, generateStaticParams, anything without preview. Not for Presentation routes.

GROQ layout: strings under web/sanity/queries/ — snippets/, components/, pages/ — wrapped in defineQuery for sanity typegen. CI runs pnpm studio:generate and pnpm --filter web run generate with git diff --exit-code guards.

Revalidation: POST /api/revalidate — HMAC-SHA256 (Sanity signed webhooks), payload validation, document-type allow-list, in-memory rate limit, fail-closed in production without SANITY_REVALIDATE_SECRET.

Lazy loading & deferred JS

Images (MediaImage):

• Native <img> with deterministic Sanity CDN URLs, full responsive srcset / sizes, hotspot-aware object-position, LQIP, hydration-safe URLs (no server/client mismatch).
• Default: loading="lazy", 0.2s fade-in on load.
• priority prop (one per page, above-the-fold LCP): loading="eager", fetchpriority="high", no lazy fade-in.
• srcset widths: 480–2400px (capped by asset width); preview/card variants use smaller sets.

Mux player (MediaVideo):

• @mux/mux-player-react/lazy — player bundle loads on demand; poster until play unless autoplay.
• Optional immediate load for hero/LCP (preload="auto", skip IO gate).

Background loops (MediaVideoLoop + hls.js):

• hls.js dynamically imported — no HLS bytes until needed.
• IntersectionObserver (400px root margin) gates attach — video loads when entering viewport.
• prefers-reduced-motion → poster only, no playback.
• Carousel slides can pre-buffer adjacent loops; stacked slides may use eager poster loading.

Carousel module:

• next/dynamic import of ModuleCarousel — ~15 KB client JS loaded only when a carousel module renders.

SanityLive:

• Conditional mount in layout — only when draft preview is actually useful (read token or active draft mode).

Tailwind CSS v4 & styles pipeline

CSS-first config — no legacy tailwind.config.js. PostCSS includes a custom rem() helper.

Two entry files (both from app/layout.tsx):

• tokens.css — loads breakpoints, spacing, font sizes before Tailwind (Tailwind drops these if they only sit after @import "tailwindcss").
• globals.css — fonts → colors → @import "tailwindcss" → breakpoints (again) → @utility typography → component CSS → safelist.

Token sources (variables/):

• breakpoints.css — single @theme { --breakpoint-* } source; drives xs: … wide: utilities and @media (width >= theme(--breakpoint-*)) in early CSS.
• colors.css — semantic --color-*; dark overrides on :root[data-theme="dark"] (manual toggle, not prefers-color-scheme alone).
• sizes.css — --space-*, --content-max-width, --container-spacing, optional --measure-rt-* for rich-text line length.
• fontsizes.css — --font-size-* / --line-height-* with breakpoint tiers; fluid root clamp() from lg (1440px) in typography layer.

Tailwind folder (tailwind/):

• theme.css — @theme extensions (fonts, colors, spacing, radii); @custom-variant dark aligned with [data-theme="dark"] on <html>.
• safelist.css — @source inline("…") for runtime/CMS-built class names.

Custom variants in breakpoints.css: portrait, landscape, touch-coarse, fine-pointer, tall, short-viewport.

Rule: change a token in variables/*.css and the matching key in tailwind/theme.css when exposing it as a utility. Keep design tokens in variables/; Tailwind folder only for @theme, @source, rare @layer.

i18n & routing (web)

Source of truth: Sanity singleton siteLanguageSettings (Settings → Site languages) — availableLanguages (order = translation fallback order), defaultLanguageId (unprefixed URLs).

• proxy.ts — CDN-backed locale list; rewrites /about → /{defaultLocale}/about internally; redirects /{defaultLocale}/about to canonical unprefixed URL.
• LanguageContext — client links via localePath.
• Reserved segments: every non-default language id is a first path segment (/de/…) — do not reuse as page slugs on the default locale site.
• Fallback when singleton missing/invalid: web uses minimal en only (fallbackSiteLocales.ts); Studio plugin uses matching FALLBACK_LANGUAGES — keep both in sync.
• Field resolution: parseLocalizedText, pickLocalizedString, pickLocalizedPortableTextBlocks in sanity/utils/sanityLocalizedText.ts; optional siteLocale from fetchSiteLanguageSettings() for fallback order.

Two repo branches for i18n strategy: main = field-level (internationalized-array); variant/document-level = one document per language. PR #62 compares both.

Sanity Presentation & Visual Editing (checklist)

• SANITY_API_READ_TOKEN in web/.env.local — required for draft enable and sanityFetch; without it, /api/draft-mode/enable returns 401.
• SANITY_STUDIO_PREVIEW_ORIGIN — exact Next origin in Presentation iframe (http://localhost:3000 vs 127.0.0.1 — pick one).
• NEXT_PUBLIC_SANITY_STUDIO_URL — Studio URL for Stega overlays.
• SANITY_STUDIO_WEB_PREVIEW_ORIGINS in Studio .env when preview target is not localhost.
• Hosted HTTPS Studio cannot iframe http://localhost (mixed content) — use a tunnel and matching HTTPS origins.

SEO, security, cookies

• sitemap.ts — per-locale alternates + x-default; robots.ts staging-aware.
• resolveSanityMetadata — canonical + hreflang per route; settings fallbacks.
• netlify.toml — CSP with frame-ancestors for sanity.studio, HSTS preload, Permissions-Policy, Referrer-Policy, X-Content-Type-Options; long cache for /_next/static/*.
• Cookie banner — optional via Settings; vanilla-cookieconsent; copy/categories from Sanity JSON; hasConsent(category), open-cookie-preferences in nav; themed with same --color-* tokens.