Skill 05 · Sanity Best Practices
Subchapter 5.17
references/project-structure.mdMarkdown4 KBView on GitHub
Best for content-only projects, API-first architectures, or when frontend is managed separately.
your-project/
├── schemaTypes/
│ ├── index.ts
│ ├── documents/
│ ├── objects/
│ └── blocks/
├── sanity.config.ts
├── sanity.cli.ts
└── package.jsonUse cases:
Best for most projects pairing Sanity with a Next.js (or other framework) app. The Studio stays standalone — Vite-based dev/builds, auto-updates, TypeGen watch mode — while living in the same repo as the frontend.
your-project/
├── studio/ # Sanity Studio (standalone)
│ ├── schemaTypes/
│ │ ├── index.ts
│ │ ├── documents/
│ │ ├── objects/
│ │ └── blocks/
│ ├── sanity.config.ts
│ ├── sanity.cli.ts # CLI + TypeGen configuration
│ └── package.json
└── web/ # Next.js (or other framework)
├── src/
│ ├── app/
│ └── sanity/
│ ├── client.ts
│ ├── live.ts # defineLive setup
│ └── queries.ts
├── sanity.types.ts # Generated types (from TypeGen)
└── package.jsonNo workspace tooling is required — each app manages its own dependencies. For larger repos, the same shape works under apps/ with npm or pnpm workspaces.
Setup:
npx sanity cors add http://localhost:3000 --credentials (or via Sanity Manage (opens in a new tab))typegen in studio/sanity.cli.ts to read queries from ../web and output types to ../web/sanity.types.ts (see typegen.md)package.json with scripts that run both dev serversOlder Next.js projects may mount the Studio inside the app at src/app/studio/[[...tool]]/page.tsx, with sanity.config.ts in the app root. This still works but is no longer recommended: it slows builds, ties Studio updates to app deploys, and rules out auto-updates and TypeGen watch mode. See nextjs.md for the rationale and migration steps.
user-profile.ts, hero-block.ts.ts for schemas/utilities, .tsx for React componentsschemaTypes/
├── index.ts # Exports all types
├── documents/ # Standalone content types
│ ├── post.ts
│ └── author.ts
├── objects/ # Embeddable/reusable types
│ ├── seo.ts
│ └── link.ts
├── blocks/ # Portable Text blocks
│ ├── hero.ts
│ └── callout.ts
└── shared/ # Shared field definitions
└── seoFields.ts| File | Purpose |
|---|---|
sanity.config.ts | Studio configuration (plugins, schema, structure) |
sanity.cli.ts | CLI configuration (project ID, dataset, TypeGen config) |
structure.ts | Custom desk structure |