DatoCMS & Astro

DatoCMS는 사이트와 앱의 디지털 콘텐츠를 관리하는 웹 기반 헤드리스 CMS입니다.

Astro와 통합

이 가이드에서는 Astro 프로젝트의 DatoCMS에서 콘텐츠 데이터를 가져온 다음 이를 페이지에 표시합니다.

전제 조건

시작하려면 다음이 필요합니다.

Astro 프로젝트 - 아직 Astro 프로젝트가 없다면 설치 가이드의 안내를 따르세요.
DatoCMS 계정 및 프로젝트 - 계정이 없으면 무료 계정에 가입할 수 있습니다.
DatoCMS 프로젝트의 읽기 전용 API 키 - 프로젝트 관리 대시보드의 “Settings” > “API Tokens”에서 찾을 수 있습니다.

자격 증명 설정

Astro 프로젝트의 루트에 .env라는 이름의 새 파일 (아직 없는 경우)을 만듭니다. DatoCMS 관리 대시보드에 있는 API 키를 사용하여 다음과 같이 새 환경 변수를 추가합니다.

DATOCMS_API_KEY=YOUR_API_KEY

TypeScript 지원을 위해 src/ 폴더의 env.d.ts 파일에서 이 환경 변수의 타입을 선언하세요. 이 파일이 없으면 파일을 만들고 다음을 추가할 수 있습니다.

interface ImportMetaEnv {
  readonly DATOCMS_API_KEY: string;
}

이제 루트 디렉터리에 다음 파일이 포함되어야 합니다.

디렉터리src/
- env.d.ts
.env
astro.config.mjs
package.json

DatoCMS에서 모델 만들기

프로젝트의 DatoCMS 관리 대시보드에서 “Settings” > “Models”로 이동하고 “Single Instance” 토글을 선택한 상태에서 “Home”이라는 새 모델을 만듭니다. 그러면 프로젝트의 홈 페이지가 생성됩니다. 이 모델에서는 페이지 제목에 대한 새 텍스트 필드를 추가합니다.

프로젝트의 “Content” 탭으로 이동하여 새로 생성된 홈 페이지를 클릭하세요. 이제 제목을 추가할 수 있습니다. 페이지를 저장하고 계속하세요.

데이터 가져오기

Astro 프로젝트에서 CMS 콘텐츠를 가져와 표시할 페이지로 이동하세요. DatoCMS GraphQL API를 사용하여 home에 대한 콘텐츠를 가져오려면 다음 쿼리를 추가하세요.

이 예시는 src/pages/index.astro에 DatoCMS의 페이지 제목을 표시합니다.

---
const response = await fetch('https://graphql.datocms.com/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
    Authorization: `Bearer ${import.meta.env.DATOCMS_API_KEY}`,
  },
  body: JSON.stringify({
    query: `query Homepage {
          home {
            title
          }
        }
      `,
  }),
});

const json = await response.json();
const data = json.data.home;
---

<h1>{data.title}</h1>

이 GraphQL 쿼리는 DatoCMS 프로젝트의 home 페이지에 있는 title 필드를 가져옵니다. 브라우저를 새로 고치면 페이지에 제목이 표시됩니다.

동적 모듈식 콘텐츠 블록 추가

DatosCMS 프로젝트에 모듈식 콘텐츠가 포함된 경우 모듈식 필드가 프로젝트에서 허용하는 각 콘텐츠 블록 (예: 텍스트 섹션, 비디오, 인용 블록 등)에 대해 해당 .astro 컴포넌트를 빌드해야 합니다.

아래 예시는 DatoCMS의 “Multiple-paragraph text” 블록을 표시하기 위한 <Text /> Astro 컴포넌트입니다.

---
export interface TextProps {
  text: string
}

export interface Props {
  item: TextProps
}

const { item } = Astro.props;
---

<div set:html={item.text} />

이러한 블록을 가져오려면 DatoCMS에서 생성한 모듈식 콘텐츠 블록을 포함하도록 GraphQL 쿼리를 편집하세요.

이 예시에서 모듈식 콘텐츠 블록의 이름은 DatoCMS에서 content입니다. 이 쿼리에는 DatoCMS 편집기에서 컨텐츠 작성자가 선택한 블록을 기반으로 모듈식 필드에 표시되어야 하는 블록을 확인하기 위한 각 항목의 고유한 _modelApiKey도 포함됩니다. 쿼리에서 받은 데이터를 기반으로 동적 렌더링을 허용하려면 Astro 템플릿의 스위치 문을 사용하세요.

다음 예시는 작성자가 홈 페이지에 렌더링된 텍스트 필드 (<Text />)와 이미지 (<Image />) 중에서 선택할 수 있도록 하는 DatoCMS 모듈식 콘텐츠 블록을 나타냅니다.

---
import Image from '../components/Image.astro';
import Text from '../components/Text.astro';

const response = await fetch('https://graphql.datocms.com/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
    Authorization: `Bearer ${import.meta.env.DATOCMS_API_KEY}`,
  },
  body: JSON.stringify({
    query: `query Homepage {
          home {
            title
            content {
              ... on ImageRecord {
                _modelApiKey
               image{
                url
               }
              }
              ... on TextRecord {
                _modelApiKey
                text(markdown: true)
              }
            }
          }
        }
      `,
  }),
});

const json = await response.json();
const data = json.data.home;
---

<h1>{data.title}</h1>
{
  data.content.map((item: any) => {
    switch (item._modelApiKey) {
      case 'image':
        return <Image item={item} />;
      case 'text':
        return <Text item={item} />;
      default:
        return null;
    }
  })
}

사이트 게시

웹사이트를 배포하려면 배포 가이드를 방문하여 선호하는 호스팅 제공업체의 지침을 따르세요.

DatoCMS 콘텐츠 변경 사항 게시

프로젝트가 Astro의 기본 정적 모드를 사용하는 경우 콘텐츠가 변경될 때 새 빌드를 트리거하도록 웹후크를 설정해야 합니다. Netlify 또는 Vercel을 호스팅 공급자로 사용하는 경우 DatoCMS에서 콘텐츠를 변경할 때 웹후크 기능을 사용하여 새 빌드를 트리거할 수 있습니다.

Netlify

Netlify에서 웹후크를 설정하려면:

사이트 대시보드로 이동하여 Build & deploy를 클릭합니다.
Continuous Deployment 탭에서 Build hooks 섹션을 찾아 Add build hook를 클릭합니다.
웹후크의 이름을 제공하고 빌드를 트리거할 브랜치를 선택합니다. Save을 클릭하고 생성된 URL을 복사하세요.

Vercel

Vercel에서 웹후크를 설정하려면 다음 안내를 따르세요.

프로젝트 대시보드로 이동하여 Settings을 클릭합니다.
Git 탭에서 Deploy Hooks 섹션을 찾습니다.
빌드를 트리거할 웹후크와 브랜치의 이름을 제공합니다. Add를 클릭하고 생성된 URL을 복사합니다.

DatoCMS에 웹후크 추가

DatoCMS 프로젝트 관리 대시보드에서 Settings 탭으로 이동하여 Webhooks를 클릭합니다. 더하기 아이콘을 클릭하여 새 웹후크을 생성하고 이름을 지정합니다. URL 필드에 선호하는 호스팅 서비스에서 생성된 URL을 붙여넣습니다. 트리거로 여러분의 필요에 맞는 옵션을 선택하세요. (예: build every time a new record is published.)