TinaCMS 스킬은(는) 무엇을 하나요?
최신 웹 애플리케이션에 TinaCMS를 통합하기 위한 완벽한 스킬입니다.
TinaCMS란?
TinaCMS는 오픈 소스, Git 기반 헤드리스 콘텐츠 관리 시스템(CMS)으로, 개발자와 콘텐츠 제작자가 콘텐츠 중심 웹사이트에서 원활하게 협업할 수 있도록 합니다.
주요 기능
-
Git 기반 저장소
- 콘텐츠가 마크다운, MDX, 또는 JSON 파일로 Git 저장소에 저장됩니다.
- 전체 버전 관리 및 변경 내역 제공
- 벤더 종속성 없음 - 콘텐츠가 저장소에 남아 있습니다.
-
시각적/컨텍스트 편집
- 나란히 보기 편집 환경
- 입력 시 변경 사항을 실시간 미리보기
- 마크다운 콘텐츠에 대한 위지위그(WYSIWYG) 방식 편집
-
스키마 기반 콘텐츠 모델링
- 코드(
tina/config.ts)에서 콘텐츠 구조 정의 - 스키마에서 자동 생성된 타입 안전 GraphQL API
- 체계적인 콘텐츠 관리를 위한 컬렉션 및 필드 시스템
- 코드(
-
유연한 배포
- TinaCloud: 관리형 서비스 (가장 쉬움, 무료 티어 제공)
- 자체 호스팅: Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
- 여러 인증 옵션 (Auth.js, 사용자 정의, 로컬 개발)
-
프레임워크 지원
- 최적: Next.js (App Router + Pages Router)
- 양호: React, Astro (실험적 시각 편집), Gatsby, Hugo, Jekyll, Remix, 11ty
- 프레임워크 비종속: 모든 프레임워크와 함께 작동 (시각 편집은 React로 제한됨)
현재 버전
- tinacms: 2.9.0 (2025년 9월)
- @tinacms/cli: 1.11.0 (2025년 10월)
- React 지원: 19.x (>=18.3.1 <20.0.0)
이 스킬을 사용해야 하는 경우
✅ TinaCMS를 사용해야 하는 경우:
-
콘텐츠 중심 사이트 구축
- 블로그 및 개인 웹사이트
- 문서 사이트
- 마케팅 웹사이트
- 포트폴리오 사이트
-
비기술적 편집자의 접근이 필요한 경우
- 코딩 지식이 없는 콘텐츠 팀
- 페이지를 관리하는 마케팅 팀
- 블로그 게시물을 작성하는 저자
-
Git 기반 워크플로우가 필요한 경우
- Git을 통한 콘텐츠 버전 관리 필요
- 풀 리퀘스트를 통한 콘텐츠 검토 필요
- 코드와 함께 저장소에 콘텐츠를 두는 것을 선호
-
시각적 편집이 필요한 경우
- 편집자가 변경 사항을 실시간으로 보고 싶어 함
- 위지위그(WYSIWYG) 환경 선호
- 나란히 보기 편집 워크플로우
❌ TinaCMS를 사용하지 말아야 하는 경우:
-
실시간 협업이 필요한 경우
- 여러 사용자가 동시에 편집 (Google Docs 스타일)
- 대신 Sanity, Contentful, 또는 Firebase 사용
-
매우 동적인 데이터
- 재고 변경이 빈번한 전자상거래 제품 카탈로그
- 실시간 대시보드
- 대신 전통적인 데이터베이스(D1, PostgreSQL) 사용
-
콘텐츠 관리가 필요하지 않은 경우
- 애플리케이션이 콘텐츠 중심이 아닌 데이터 중심인 경우
- 하드코딩된 콘텐츠로 충분한 경우
프레임워크별 설정 패턴
프레임워크 선택에 따라 적절한 설정 패턴을 사용하십시오.
1. Next.js 설정 (권장)
App Router (Next.js 13+)
단계:
-
TinaCMS 초기화:
npx @tinacms/cli@latest init- 공개 자산 디렉토리를 묻는 메시지가 표시되면
public입력
- 공개 자산 디렉토리를 묻는 메시지가 표시되면
-
package.json 스크립트 업데이트:
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
환경 변수 설정:
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token -
개발 서버 시작:
npm run dev -
관리 인터페이스 접속:
http://localhost:3000/admin/index.html
생성된 주요 파일:
tina/config.ts- 스키마 설정app/admin/[[...index]]/page.tsx- 관리 UI 라우트 (App Router 사용 시)
템플릿: templates/nextjs/tina-config-app-router.ts 참조
Pages Router (Next.js 12 이하)
설정은 동일하지만, 관리 라우트는:
pages/admin/[[...index]].tsx(app 디렉토리 대신)
데이터 가져오기 패턴:
// pages/posts/[slug].tsx
import { client } from '../../tina/__generated__/client'
import { useTina } from 'tinacms/dist/react'
export default function BlogPost(props) {
// 시각적 편집을 위한 하이드레이션
const { data } = useTina({
query: props.query,
variables: props.variables,
data: props.data
})
return (
<article>
<h1>{data.post.title}</h1>
<div dangerouslySetInnerHTML={{ __html: data.post.body }} />
</article>
)
}
export async function getStaticProps({ params }) {
const response = await client.queries.post({
relativePath: `${params.slug}.md`
})
return {
props: {
data: response.data,
query: response.query,
variables: response.variables
}
}
}
export async function getStaticPaths() {
const response = await client.queries.postConnection()
const paths = response.data.postConnection.edges.map((edge) => ({
params: { slug: edge.node._sys.filename }
}))
return { paths, fallback: 'blocking' }
}
템플릿: templates/nextjs/tina-config-pages-router.ts 참조
2. Vite + React 설정
단계:
-
의존성 설치:
npm install react@^19 react-dom@^19 tinacms -
TinaCMS 초기화:
npx @tinacms/cli@latest init- 공개 자산 디렉토리를
public으로 설정
- 공개 자산 디렉토리를
-
vite.config.ts 업데이트:
import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { port: 3000 // TinaCMS 기본값 } }) -
package.json 스크립트 업데이트:
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
관리 인터페이스 생성:
옵션 A: 수동 라우트 (React Router)
// src/pages/Admin.tsx import TinaCMS from 'tinacms' export default function Admin() { return <div id="tina-admin" /> }옵션 B: 직접 HTML
<!-- public/admin/index.html --> <!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <title>Tina CMS</title> <meta name="viewport" content="width=device-width, initial-scale=1" /> </head> <body> <div id="root"></div> <script type="module" src="/@fs/[path-to-tina-admin]"></script> </body> </html> -
시각적 편집을 위해 useTina 훅 사용:
import { useTina } from 'tinacms/dist/react' import { client } from '../tina/__generated__/client' function BlogPost({ initialData }) { const { data } = useTina({ query: initialData.query, variables: initialData.variables, data: initialData.data }) return ( <article> <h1>{data.post.title}</h1> <div>{/* 본문 렌더링 */}</div> </article> ) } -
환경 변수 설정:
# .env VITE_TINA_CLIENT_ID=your_client_id VITE_TINA_TOKEN=your_read_only_token
템플릿: templates/vite-react/ 참조
3. Astro 설정
단계:
-
공식 스타터 사용 (권장):
npx create-tina-app@latest --template tina-astro-starter또는 수동으로 초기화:
npx @tinacms/cli@latest init -
package.json 스크립트 업데이트:
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
Astro 설정:
// astro.config.mjs import { defineConfig } from 'astro/config' import react from '@astro/react' export default defineConfig({ integrations: [react()] // Tina 관리자에 필요 }) -
시각적 편집 (실험적):
- React 구성 요소 필요
- 대화형 편집을 위해
client:tinaDirective사용 - 전체 시각적 편집은 2025년 10월 기준 실험적 단계
-
환경 변수 설정:
# .env PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token
최적 대상: 콘텐츠 중심 정적 사이트, 문서, 블로그
템플릿: templates/astro/ 참조
4. 프레임워크 비종속 설정
적용 대상: Hugo, Jekyll, Eleventy, Gatsby, Remix 또는 모든 프레임워크
단계:
-
TinaCMS 초기화:
npx @tinacms/cli@latest init -
수동으로 빌드 스크립트 설정:
{ "scripts": { "dev": "tinacms dev -c \"<your-dev-command>\"", "build": "tinacms build && <your-build-command>" } } -
관리 인터페이스:
http://localhost:<port>/admin/index.html에 자동 생성- 포트는 프레임워크에 따라 다름
-
데이터 가져오기:
- 시각적 편집 없음 (사이드바만 가능)
- Git 기반 인터페이스를 통해 콘텐츠 편집
- 변경 사항이 파일에 직접 저장됨
-
환경 변수 설정:
TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token
제한 사항:
- 시각적 편집 없음 (React 전용 기능)
- 수동 통합 필요
- 사이드바 기반 편집만 가능
스키마 모델링 모범 사례
tina/config.ts에서 콘텐츠 구조를 정의하십시오.
기본 설정 구조
import { defineConfig } from 'tinacms'
export default defineConfig({
// 브랜치 설정
branch: process.env.GITHUB_BRANCH ||
process.env.VERCEL_GIT_COMMIT_REF ||
'main',
// TinaCloud 자격 증명 (관리 서비스 사용 시)
clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
token: process.env.TINA_TOKEN,
// 빌드 설정
build: {
outputFolder: 'admin',
publicFolder: 'public',
},
// 미디어 설정
media: {
tina: {
mediaRoot: '',
publicFolder: 'public',
},
},
// 콘텐츠 스키마
schema: {
collections: [
// 여기에 컬렉션 정의
],
},
})
컬렉션
컬렉션 = 콘텐츠 유형 + 디렉토리 매핑
{
name: 'post', // 단수, 내부 이름 (API에서 사용)
label: 'Blog Posts', // 복수, 표시 이름 (관리자에 표시)
path: 'content/posts', // 파일이 저장되는 디렉토리
format: 'mdx', // 파일 형식: md, mdx, markdown, json, yaml, toml
fields: [/* ... */] // 필드 정의 배열
}
주요 속성:
name: 내부 식별자 (영숫자 + 밑줄만 가능)label: 관리 인터페이스를 위한 사람이 읽을 수 있는 이름path: 프로젝트 루트를 기준으로 한 파일 경로format: 파일 확장자 (기본값: 'md')fields: 콘텐츠 구조 정의
필드 유형 참조
| 유형 | 사용 사례 | 예시 |
|---|---|---|
string | 짧은 텍스트 (한 줄) | 제목, 슬러그, 저자 이름 |
rich-text | 긴 서식 있는 콘텐츠 | 블로그 본문, 페이지 콘텐츠 |
number | 숫자 값 | 가격, 수량, 평점 |
datetime | 날짜/시간 값 | 게시일, 이벤트 시간 |
boolean | 참/거짓 토글 | 초안 상태, 추천 플래그 |
image | 이미지 업로드 | 히어로 이미지, 썸네일, 아바타 |
reference | 다른 문서에 대한 링크 | 저자, 카테고리, 관련 게시물 |
object | 중첩 필드 그룹 | SEO 메타데이터, 소셜 링크 |
전체 참조: references/field-types-reference.md 참조
컬렉션 템플릿
블로그 게시물 컬렉션
{
name: 'post',
label: 'Blog Posts',
path: 'content/posts',
format: 'mdx',
fields: [
{
type: 'string',
name: 'title',
label: 'Title',
isTitle: true, // 콘텐츠 목록에 표시
required: true
},
{
type: 'string',
name: 'excerpt',
label: 'Excerpt',
ui: {
component: 'textarea' // 여러 줄 입력
}
},
{
type: 'image',
name: 'coverImage',
label: 'Cover Image'
},
{
type: 'datetime',
name: 'date',
label: 'Published Date',
required: true
},
{
type: 'reference',
name: 'author',
label: 'Author',
collections: ['author'] // 저자 컬렉션 참조
},
{
type: 'boolean',
name: 'draft',
label: 'Draft',
description: 'If checked, post will not be published',
required: true
},
{
type: 'rich-text',
name: 'body',
label: 'Body',
isBody: true // 주요 콘텐츠 영역
}
],
ui: {
router: ({ document }) => `/blog/${document._sys.filename}`
}
}
템플릿: templates/collections/blog-post.ts 참조
문서 페이지 컬렉션
{
name: 'doc',
label: 'Documentation',
path: 'content/docs',
format: 'mdx',
fields: [
{
type: 'string',
name: 'title',
label: 'Title',
isTitle: true,
required: true
},
{
type: 'string',
name: 'description',
label: 'Description',
ui: {
component: 'textarea'
}
},
{
type: 'number',
name: 'order',
label: 'Order',
description: 'Sort order in sidebar'
},
{
type: 'rich-text',
name: 'body',
label: 'Body',
isBody: true,
templates: [
// MDX 구성 요소를 여기에 정의할 수 있습니다.
]
}
],
ui: {
router: ({ document }) => {
const breadcrumbs = document._sys.breadcrumbs.join('/')
return `/docs/${breadcrumbs}`
}
}
}
템플릿: templates/collections/doc-page.ts 참조
저자 컬렉션 (참조 대상)
{
name: 'author',
label: 'Authors',
path: 'content/authors',
format: 'json', // 구조화된 데이터에 JSON 사용
fields: [
{
type: 'string',
name: 'name',
label: 'Name',
isTitle: true,
required: true
},
{
type: 'string',
name: 'email',
label: 'Email',
ui: {
validate: (value) => {
if (!value?.includes('@')) {
return 'Invalid email address'
}
}
}
},