2nd/10_Wiki/Topics/Frontend/Sanity Studio.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-sanity-studio	Sanity Studio	10_Wiki/Topics	verified	self	Sanity Sanity CMS Sanity Headless	none	A	0.9	applied	headless-cms sanity content structured-content		2026-05-10	pending	language framework TypeScript Sanity v3 + React

Sanity Studio

매 한 줄

"매 Sanity Studio는 customizable single-page editor 를 wrap 한 headless CMS". v3 (2023) 부터 React 기반 fully composable, 매 schema-as-code (TS), GROQ query language, Portable Text, real-time collaboration. 2026 기준 Contentful / Strapi 의 main alternative — 매 dev experience + customization 이 강점.

매 핵심

매 컴포넌트

• Studio: editor SPA (React, self-host or Sanity hosted)
• Content Lake: cloud datastore (도큐먼트 store)
• GROQ: query language (graph + projection)
• Portable Text: rich text JSON spec

매 schema 방식

• TS 로 schema 정의 → studio UI 자동 생성
• Field type: string, number, image, reference, array, object, slug, portable text...
• Custom input component 도 React 로 작성 가능

매 응용

1. Marketing sites (Next.js + Sanity).
2. Editorial / publishing (long-form, structured).
3. E-commerce content (product copy, lookbooks).
4. Multi-channel content (web + mobile + email).

💻 패턴

Schema 정의

// schemas/post.ts
import { defineType, defineField } from "sanity";

export const post = defineType({
  name: "post",
  title: "Post",
  type: "document",
  fields: [
    defineField({ name: "title", type: "string", validation: (R) => R.required() }),
    defineField({
      name: "slug",
      type: "slug",
      options: { source: "title", maxLength: 96 },
    }),
    defineField({ name: "author", type: "reference", to: [{ type: "author" }] }),
    defineField({ name: "body", type: "array", of: [{ type: "block" }, { type: "image" }] }),
    defineField({ name: "publishedAt", type: "datetime" }),
  ],
});

sanity.config.ts

import { defineConfig } from "sanity";
import { structureTool } from "sanity/structure";
import { visionTool } from "@sanity/vision";
import { post, author } from "./schemas";

export default defineConfig({
  name: "default",
  title: "My Studio",
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: "production",
  plugins: [structureTool(), visionTool()],
  schema: { types: [post, author] },
});

GROQ query

import { createClient } from "@sanity/client";

const client = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: "production",
  apiVersion: "2026-01-01",
  useCdn: true,
});

const posts = await client.fetch<Post[]>(`
  *[_type == "post" && publishedAt < now()] | order(publishedAt desc) [0...10] {
    _id, title, slug, publishedAt,
    "authorName": author->name,
    "image": mainImage.asset->url
  }
`);

Next.js 15 integration with revalidate

// app/posts/[slug]/page.tsx
import { client } from "@/lib/sanity";
import { notFound } from "next/navigation";

export const revalidate = 60;

export default async function Page({
  params,
}: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const post = await client.fetch(
    `*[_type == "post" && slug.current == $slug][0]`,
    { slug },
    { next: { tags: [`post:${slug}`] } },
  );
  if (!post) notFound();
  return <article>{post.title}</article>;
}

On-demand revalidation via webhook

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";
import { parseBody } from "next-sanity/webhook";

export async function POST(req: Request) {
  const { isValidSignature, body } = await parseBody<{ slug: string; _type: string }>(
    req, process.env.SANITY_REVALIDATE_SECRET!,
  );
  if (!isValidSignature) return Response.json({ ok: false }, { status: 401 });
  if (body?._type === "post") revalidateTag(`post:${body.slug}`);
  return Response.json({ ok: true });
}

Portable Text rendering

import { PortableText, type PortableTextComponents } from "@portabletext/react";

const components: PortableTextComponents = {
  types: {
    image: ({ value }) => <img src={value.asset.url} alt={value.alt} />,
  },
  marks: {
    link: ({ value, children }) => <a href={value.href}>{children}</a>,
  },
};

export function Body({ value }: { value: any }) {
  return <PortableText value={value} components={components} />;
}

Custom input component

// schemas/inputs/EmojiInput.tsx
import { TextInput, Card } from "@sanity/ui";
import { set, unset } from "sanity";

export function EmojiInput(props: any) {
  return (
    <Card padding={2}>
      <TextInput
        value={props.value || ""}
        onChange={(e) =>
          props.onChange(e.currentTarget.value ? set(e.currentTarget.value) : unset())
        }
      />
    </Card>
  );
}

TypeGen for type-safe queries

npx sanity@latest typegen generate
# generates sanity.types.ts with full TS types per query

매 결정 기준

상황	Approach
Dev-first, code-driven schema	Sanity
Non-tech editor, off-the-shelf	Contentful / Storyblok
Self-host, full control	Strapi / Payload
매 real-time collab + custom UI	Sanity (강점)
Tiny site / blog	MDX in repo (overkill 회피)

기본값: Sanity v3 + Next.js 15 + GROQ + Portable Text + TypeGen.

🔗 Graph

🤖 LLM 활용

언제: Marketing / editorial site, 매 dev-driven schema, custom editor needs. 매 Next.js + cloud CMS 의 경우. 언제 X: Tiny static blog (MDX 충분), enterprise with strict on-prem.

❌ 안티패턴

• useCdn: true for drafts: preview 모드에서 매 stale data. Preview 시 false.
• Naked GROQ in components: 매 query 를 lib/queries.ts 로 모으고 typegen.
• No webhook revalidation: 매 시간 단위 revalidate 만 → editor 답답함. On-demand webhook 필수.
• Schema in studio UI: 매 schema-as-code 가 v3 의 핵심. 매 GUI 편집 X.

🧪 검증 / 중복

• Verified (sanity.io docs v3, 2026).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Sanity Studio full content