Sanity CMS 완벽 가이드 | Headless CMS·구조화된 콘텐츠·GROQ·실시간·실전 활용

2026년 4월 7일 · 16분 읽기 · 수정 2026년 4월 7일 중급

이 글의 핵심

Sanity CMS로 유연한 콘텐츠 관리를 구현하는 완벽 가이드입니다. Schema 정의, GROQ 쿼리, 실시간 업데이트, Next.js 통합까지 실전 예제로 정리했습니다.

실무 경험 공유: WordPress에서 Sanity로 전환하면서, 콘텐츠 관리가 자유로워지고 개발자 경험이 크게 향상된 경험을 공유합니다.

들어가며: “CMS가 불편해요”

실무 문제 시나리오

시나리오 1: 스키마가 고정돼 있어요
WordPress는 제한적입니다. Sanity는 완전히 커스터마이징 가능합니다.

시나리오 2: 개발자 경험이 나빠요
기존 CMS는 불편합니다. Sanity는 개발자 친화적입니다.

시나리오 3: 실시간 협업이 필요해요
동시 편집이 어렵습니다. Sanity는 실시간 협업을 지원합니다.

1. Sanity란?

핵심 특징

Sanity는 구조화된 콘텐츠 플랫폼입니다.

주요 장점:

유연한 스키마: 완전히 커스터마이징
GROQ: 강력한 쿼리 언어
실시간: 실시간 업데이트
Portable Text: 리치 텍스트
이미지 처리: 자동 최적화

2. 프로젝트 설정

설치

npm create sanity@latest

프로젝트 구조

my-sanity-project/
├── sanity/
│   ├── schemas/
│   │   ├── post.ts
│   │   └── author.ts
│   ├── sanity.config.ts
│   └── sanity.cli.ts
└── app/

3. Schema 정의

Post Schema

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

export default defineType({
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Title',
      type: 'string',
      validation: (Rule) => Rule.required().min(10).max(100),
    }),
    defineField({
      name: 'slug',
      title: 'Slug',
      type: 'slug',
      options: {
        source: 'title',
        maxLength: 96,
      },
      validation: (Rule) => Rule.required(),
    }),
    defineField({
      name: 'author',
      title: 'Author',
      type: 'reference',
      to: [{ type: 'author' }],
    }),
    defineField({
      name: 'mainImage',
      title: 'Main image',
      type: 'image',
      options: {
        hotspot: true,
      },
    }),
    defineField({
      name: 'categories',
      title: 'Categories',
      type: 'array',
      of: [{ type: 'reference', to: { type: 'category' } }],
    }),
    defineField({
      name: 'publishedAt',
      title: 'Published at',
      type: 'datetime',
    }),
    defineField({
      name: 'body',
      title: 'Body',
      type: 'blockContent',
    }),
  ],
});

4. GROQ 쿼리

기본 쿼리

// lib/sanity.ts
import { createClient } from '@sanity/client';

export const client = createClient({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  apiVersion: '2024-01-01',
  useCdn: true,
});

// 모든 포스트
const posts = await client.fetch(`*[_type == "post"]`);

// 필터링
const publishedPosts = await client.fetch(`
  *[_type == "post" && publishedAt < now()] | order(publishedAt desc)
`);

// 특정 필드만
const posts = await client.fetch(`
  *[_type == "post"] {
    title,
    slug,
    publishedAt
  }
`);

Join (Reference)

const postsWithAuthor = await client.fetch(`
  *[_type == "post"] {
    title,
    slug,
    author->{
      name,
      image
    }
  }
`);

파라미터

const post = await client.fetch(
  `*[_type == "post" && slug.current == $slug][0] {
    title,
    body,
    author->{name}
  }`,
  { slug: 'my-post' }
);

5. Next.js 통합

포스트 목록

// app/blog/page.tsx
import { client } from '@/lib/sanity';

async function getPosts() {
  return await client.fetch(`
    *[_type == "post"] | order(publishedAt desc) {
      _id,
      title,
      slug,
      publishedAt,
      author->{name}
    }
  `);
}

export default async function BlogPage() {
  const posts = await getPosts();

  return (
    <ul>
      {posts.map((post) => (
        <li key={post._id}>
          <a href={`/blog/${post.slug.current}`}>{post.title}</a>
        </li>
      ))}
    </ul>
  );
}

포스트 상세

// app/blog/[slug]/page.tsx
import { client } from '@/lib/sanity';
import { PortableText } from '@portabletext/react';

async function getPost(slug: string) {
  return await client.fetch(
    `*[_type == "post" && slug.current == $slug][0] {
      title,
      body,
      author->{name, image},
      mainImage
    }`,
    { slug }
  );
}

export default async function PostPage({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <PortableText value={post.body} />
    </article>
  );
}

6. 이미지 최적화

next-sanity

npm install next-sanity

import imageUrlBuilder from '@sanity/image-url';
import { client } from './sanity';

const builder = imageUrlBuilder(client);

export function urlFor(source: any) {
  return builder.image(source);
}

// 사용
<img
  src={urlFor(post.mainImage).width(800).height(400).url()}
  alt={post.title}
/>

7. 실시간 업데이트

'use client';

import { useEffect, useState } from 'react';
import { client } from '@/lib/sanity';

export default function RealtimePosts({ initialPosts }) {
  const [posts, setPosts] = useState(initialPosts);

  useEffect(() => {
    const subscription = client
      .listen(`*[_type == "post"]`)
      .subscribe((update) => {
        if (update.type === 'mutation') {
          setPosts((prev) => {
            // 업데이트 로직
            return [...prev];
          });
        }
      });

    return () => subscription.unsubscribe();
  }, []);

  return (
    <ul>
      {posts.map((post) => (
        <li key={post._id}>{post.title}</li>
      ))}
    </ul>
  );
}

정리 및 체크리스트

핵심 요약

Sanity: Headless CMS
유연한 스키마: 완전히 커스터마이징
GROQ: 강력한 쿼리 언어
실시간: 실시간 업데이트
Portable Text: 리치 텍스트
이미지 처리: 자동 최적화

구현 체크리스트

같이 보면 좋은 글

Next.js App Router 가이드
Astro 완벽 가이드
Contentful 가이드

이 글에서 다루는 키워드

Sanity, CMS, Headless CMS, GROQ, Content, Next.js, Backend

자주 묻는 질문 (FAQ)

Q. WordPress와 비교하면 어떤가요?

A. Sanity가 훨씬 유연하고 개발자 친화적입니다. WordPress는 더 많은 플러그인을 제공합니다.

Q. Contentful과 비교하면 어떤가요?

A. Sanity가 더 유연하고 실시간 기능이 좋습니다. Contentful은 더 성숙합니다.

Q. 무료로 사용할 수 있나요?

A. 네, 무료 플랜이 있습니다. 3 사용자, 10K 문서까지 무료입니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, Nike, Figma 등 많은 기업에서 사용합니다.