Communitygithub.com

TinaCMS 스킬

Git 기반 TinaCMS를 사용하여 콘텐츠 중심의 사이트를 구축합니다. 블로그, 문서, 마케팅 사이트에 비기술적인 편집자를 위한 시각적 편집 및 콘텐츠 관리를 제공합니다.

TinaCMS 스킬란 무엇인가요?

이 스킬은 오픈 소스이면서 Git에 백업된 헤드리스 CMS인 TinaCMS를 최신 웹 애플리케이션에 통합하기 위한 종합 가이드를 제공합니다. TinaCMS는 콘텐츠를 마크다운, MDX, 또는 JSON 파일로 Git 저장소에 저장하여 버전 관리와 전체 변경 내역을 제공하며, 벤더 종속성을 없앱니다. Next.js, Vite+React, Astro와 같은 다양한 프레임워크를 지원하며, 시각적 편집, 실시간 미리보기, 스키마 기반 콘텐츠 모델링, 그리고 자체 호스팅(Cloudflare Workers, Vercel Functions 등) 또는 TinaCloud 관리 서비스를 통한 유연한 배포 옵션을 제공합니다. 이 스킬은 프레임워크별 설정 패턴, 블로그 게시물, 문서 페이지, 저자 컬렉션을 포함한 스키마 모델링 모범 사례, 필드 유형 참조, 콘텐츠 API를 통한 데이터 가져오기 방법, 그리고 일반적인 문제 해결(ESbuild 컴파일 오류, 모듈 해석 문제, Docker 바인딩 문제)을 다루어, 비기술적 편집자가 참여하는 콘텐츠 중심 웹사이트를 구축하는 개발자에게 포괄적인 참고 자료를 제공합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/tinacms

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

TinaCMS 스킬은(는) 무엇을 하나요?

최신 웹 애플리케이션에 TinaCMS를 통합하기 위한 완벽한 스킬입니다.


TinaCMS란?

TinaCMS는 오픈 소스, Git 기반 헤드리스 콘텐츠 관리 시스템(CMS)으로, 개발자와 콘텐츠 제작자가 콘텐츠 중심 웹사이트에서 원활하게 협업할 수 있도록 합니다.

주요 기능

  1. Git 기반 저장소

    • 콘텐츠가 마크다운, MDX, 또는 JSON 파일로 Git 저장소에 저장됩니다.
    • 전체 버전 관리 및 변경 내역 제공
    • 벤더 종속성 없음 - 콘텐츠가 저장소에 남아 있습니다.
  2. 시각적/컨텍스트 편집

    • 나란히 보기 편집 환경
    • 입력 시 변경 사항을 실시간 미리보기
    • 마크다운 콘텐츠에 대한 위지위그(WYSIWYG) 방식 편집
  3. 스키마 기반 콘텐츠 모델링

    • 코드(tina/config.ts)에서 콘텐츠 구조 정의
    • 스키마에서 자동 생성된 타입 안전 GraphQL API
    • 체계적인 콘텐츠 관리를 위한 컬렉션 및 필드 시스템
  4. 유연한 배포

    • TinaCloud: 관리형 서비스 (가장 쉬움, 무료 티어 제공)
    • 자체 호스팅: Cloudflare Workers, Vercel Functions, Netlify Functions, AWS Lambda
    • 여러 인증 옵션 (Auth.js, 사용자 정의, 로컬 개발)
  5. 프레임워크 지원

    • 최적: 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를 사용해야 하는 경우:

  1. 콘텐츠 중심 사이트 구축

    • 블로그 및 개인 웹사이트
    • 문서 사이트
    • 마케팅 웹사이트
    • 포트폴리오 사이트
  2. 비기술적 편집자의 접근이 필요한 경우

    • 코딩 지식이 없는 콘텐츠 팀
    • 페이지를 관리하는 마케팅 팀
    • 블로그 게시물을 작성하는 저자
  3. Git 기반 워크플로우가 필요한 경우

    • Git을 통한 콘텐츠 버전 관리 필요
    • 풀 리퀘스트를 통한 콘텐츠 검토 필요
    • 코드와 함께 저장소에 콘텐츠를 두는 것을 선호
  4. 시각적 편집이 필요한 경우

    • 편집자가 변경 사항을 실시간으로 보고 싶어 함
    • 위지위그(WYSIWYG) 환경 선호
    • 나란히 보기 편집 워크플로우

❌ TinaCMS를 사용하지 말아야 하는 경우:

  1. 실시간 협업이 필요한 경우

    • 여러 사용자가 동시에 편집 (Google Docs 스타일)
    • 대신 Sanity, Contentful, 또는 Firebase 사용
  2. 매우 동적인 데이터

    • 재고 변경이 빈번한 전자상거래 제품 카탈로그
    • 실시간 대시보드
    • 대신 전통적인 데이터베이스(D1, PostgreSQL) 사용
  3. 콘텐츠 관리가 필요하지 않은 경우

    • 애플리케이션이 콘텐츠 중심이 아닌 데이터 중심인 경우
    • 하드코딩된 콘텐츠로 충분한 경우

프레임워크별 설정 패턴

프레임워크 선택에 따라 적절한 설정 패턴을 사용하십시오.

1. Next.js 설정 (권장)

App Router (Next.js 13+)

단계:

  1. TinaCMS 초기화:

    npx @tinacms/cli@latest init
    
    • 공개 자산 디렉토리를 묻는 메시지가 표시되면 public 입력
  2. package.json 스크립트 업데이트:

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. 환경 변수 설정:

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    
  4. 개발 서버 시작:

    npm run dev
    
  5. 관리 인터페이스 접속:

    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 설정

단계:

  1. 의존성 설치:

    npm install react@^19 react-dom@^19 tinacms
    
  2. TinaCMS 초기화:

    npx @tinacms/cli@latest init
    
    • 공개 자산 디렉토리를 public으로 설정
  3. vite.config.ts 업데이트:

    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      server: {
        port: 3000  // TinaCMS 기본값
      }
    })
    
  4. package.json 스크립트 업데이트:

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. 관리 인터페이스 생성:

    옵션 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>
    
  6. 시각적 편집을 위해 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>
      )
    }
    
  7. 환경 변수 설정:

    # .env
    VITE_TINA_CLIENT_ID=your_client_id
    VITE_TINA_TOKEN=your_read_only_token
    

템플릿: templates/vite-react/ 참조


3. Astro 설정

단계:

  1. 공식 스타터 사용 (권장):

    npx create-tina-app@latest --template tina-astro-starter
    

    또는 수동으로 초기화:

    npx @tinacms/cli@latest init
    
  2. package.json 스크립트 업데이트:

    {
      "scripts": {
        "dev": "tinacms dev -c \"astro dev\"",
        "build": "tinacms build && astro build",
        "preview": "astro preview"
      }
    }
    
  3. Astro 설정:

    // astro.config.mjs
    import { defineConfig } from 'astro/config'
    import react from '@astro/react'
    
    export default defineConfig({
      integrations: [react()]  // Tina 관리자에 필요
    })
    
  4. 시각적 편집 (실험적):

    • React 구성 요소 필요
    • 대화형 편집을 위해 client:tinaDirective 사용
    • 전체 시각적 편집은 2025년 10월 기준 실험적 단계
  5. 환경 변수 설정:

    # .env
    PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

최적 대상: 콘텐츠 중심 정적 사이트, 문서, 블로그

템플릿: templates/astro/ 참조


4. 프레임워크 비종속 설정

적용 대상: Hugo, Jekyll, Eleventy, Gatsby, Remix 또는 모든 프레임워크

단계:

  1. TinaCMS 초기화:

    npx @tinacms/cli@latest init
    
  2. 수동으로 빌드 스크립트 설정:

    {
      "scripts": {
        "dev": "tinacms dev -c \"<your-dev-command>\"",
        "build": "tinacms build && <your-build-command>"
      }
    }
    
  3. 관리 인터페이스:

    • http://localhost:<port>/admin/index.html에 자동 생성
    • 포트는 프레임워크에 따라 다름
  4. 데이터 가져오기:

    • 시각적 편집 없음 (사이드바만 가능)
    • Git 기반 인터페이스를 통해 콘텐츠 편집
    • 변경 사항이 파일에 직접 저장됨
  5. 환경 변수 설정:

    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'
          }
        }
      }
    },

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

관련 스킬