Cosmic & Astro

Cosmic은 콘텐츠를 관리하기 위한 관리 대시보드와 다양한 프런트엔드 도구와 통합할 수 있는 API를 제공하는 헤드리스 CMS입니다.

전제 조건

Astro 프로젝트 - 새로운 Astro 프로젝트를 시작하고 싶다면 설치 가이드를 읽어보세요. 이 가이드는 스타일링을 위해 Tailwind CSS를 사용하는 Astro 헤드리스 CMS 테마의 단순화된 버전을 따릅니다.
Cosmic 계정과 Bucket - Cosmic 계정이 없다면 무료로 계정을 만드세요. 계정을 생성한 후에는 비어 있는 새 프로젝트를 생성하라는 메시지가 표시됩니다. 이 가이드에 사용된 모든 콘텐츠를 자동으로 가져오는 데 사용할 수 있는 Simple Astro Blog 템플릿 (Astro 헤드리스 CMS 테마와 동일한 템플릿)도 있습니다.
Cosmic API keys - Cosmic 대시보드에서 Cosmic에 연결하려면 Bucket slug 및 Bucket read key를 모두 찾아야 합니다.

Cosmic과 Astro의 통합

필요한 종속성 설치

Cosmic Bucket에서 데이터를 가져오려면 Cosmic JavaScript SDK를 추가하세요.

npm install @cosmicjs/sdk

pnpm add @cosmicjs/sdk

yarn add @cosmicjs/sdk

API 키 구성

Astro 프로젝트의 루트에 .env 파일을 만듭니다 (아직 존재하지 않는 경우). Cosmic 대시보드에서 사용할 수 있는 Bucket slug 및 Bucket read key를 공개 환경 변수로 추가하세요.

PUBLIC_COSMIC_BUCKET_SLUG=YOUR_BUCKET_SLUG
PUBLIC_COSMIC_READ_KEY=YOUR_READ_KEY

Cosmic에서 데이터 가져오기

cosmic.js라는 새 파일을 만듭니다. 이 파일을 프로젝트의 src/lib 폴더 안에 넣으세요.

SDK 및 환경 변수를 사용하여 Cosmic에서 데이터를 가져오려면 다음 코드를 추가합니다.

아래 예시에서는 Cosmic posts 객체에서 메타데이터를 가져오는 getAllPosts()라는 함수를 만듭니다.

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: import.meta.env.PUBLIC_COSMIC_BUCKET_SLUG,
  readKey: import.meta.env.PUBLIC_COSMIC_READ_KEY
})

export async function getAllPosts() {
  const data = await cosmic.objects
    .find({
      type: 'posts'
    })
    .props('title,slug,metadata,created_at')
  return data.objects
}

Cosmic 문서에서 쿼리에 대해 자세히 알아보세요.

.astro 컴포넌트에서 쿼리 함수를 가져옵니다. 데이터를 가져온 후 쿼리 결과를 Astro 템플릿에서 사용할 수 있습니다.

다음 예시에서는 Cosmic posts에서 메타데이터를 가져오고 이 값을 <Card /> 컴포넌트에 props로 전달하여 블로그 게시물 목록을 만드는 방법을 보여줍니다.

---
import Card from '../components/Card.astro'
import { getAllPosts } from '../lib/cosmic'

const data = await getAllPosts()
---

<section>
  <ul class="grid gap-8 md:grid-cols-2">
    {
      data.map((post) => (
        <Card
          title={post.title}
          href={post.slug}
          body={post.metadata.excerpt}
          tags={post.metadata.tags.map((tag) => tag)}
        />
      ))
    }
  </ul>
</section>

Card 컴포넌트의 소스 코드 보기

Astro와 Cosmic으로 블로그 만들기

Cosmic을 사용하여 Astro 블로그 콘텐츠를 관리하고 웹후크를 생성하여 새 콘텐츠를 업데이트하거나 추가할 때 웹사이트를 자동으로 재배포할 수 있습니다.

Cosmic 콘텐츠 객체

다음 지침에서는 Cosmic에 posts라는 Object Type이 있다고 가정합니다. 각 개별 블로그 게시물은 다음 메타필드를 사용하여 Cosmic 대시보드에 정의된 post입니다.

Text input - Author
Image - Cover Image
Repeater - Tags
- Text input - Title
Text area - Excerpt
Rich Text - Content

Astro에서 블로그 게시물 목록 표시하기

위와 동일한 데이터 가져오기 방법을 사용하여 스크립트 파일에서 getAllPosts() 쿼리를 가져오고 데이터를 기다립니다 (await 사용). 이 함수는 동적으로 표시될 수 있는 각 post에 대한 메타데이터를 제공합니다.

아래 예시에서는 이러한 값을 <Card /> 컴포넌트에 전달하여 형식화된 블로그 게시물 목록을 표시합니다.

---
import Card from '../components/Card.astro'
import { getAllPosts } from '../lib/cosmic'

const data = await getAllPosts()
---

<section>
  <ul class="grid gap-8 md:grid-cols-2">
    {
      data.map((post) => (
        <Card
          title={post.title}
          href={post.slug}
          body={post.metadata.excerpt}
          tags={post.metadata.tags.map((tag) => tag)}
        />
      ))
    }
  </ul>
</section>

Astro로 개별 블로그 게시물 생성하기

각 블로그 게시물의 전체 콘텐츠가 포함된 개별 페이지를 생성하려면 src/pages/blog/[slug].astro에서 동적 라우팅 페이지를 생성하세요.

이 페이지는 getStaticPaths() 함수를 내보내 각 post 객체에서 반환된 slug에서 페이지 경로를 생성합니다. 이 함수는 빌드 시 호출되며 모든 블로그 게시물을 한 번에 생성하고 렌더링합니다.

Cosmic에서 데이터에 액세스하려면:

getStaticPaths() 내부에서 Cosmic을 쿼리하여 각 게시물에 대한 데이터를 가져와 함수에 제공합니다.
각 post.slug를 경로 매개변수로 사용하여 각 블로그 게시물에 대한 URL을 생성합니다.
Astro.props 내부의 각 post을 반환하여 렌더링을 위해 페이지 컴포넌트의 HTML 템플릿 부분에 게시물 데이터를 사용할 수 있도록 합니다.

아래 HTML 마크업은 게시물의 title, cover image, rich text content (블로그 게시물의 전체 콘텐츠) 등 Cosmic의 다양한 데이터를 사용합니다. Cosmic의 리치 텍스트 콘텐츠를 표시하는 요소에 set:html을 사용하면 Cosmic에서 가져온 것과 똑같이 페이지의 HTML 요소를 렌더링할 수 있습니다.

---
import { getAllPosts } from '../../lib/cosmic'
import { Image } from 'astro:assets'

export async function getStaticPaths() {
  const data = (await getAllPosts()) || []

  return data.map((post) => {
    return {
      params: { slug: post.slug },
      props: { post }
    }
  })
}

const { post } = Astro.props
---

<article class="mx-auto max-w-screen-md pt-20">
  <section class="border-b pb-8">
    <h1 class="text-4xl font-bold">{post.title}</h1>
    <div class="my-4"></div>
    <span class="text-sm font-semibold">{post.metadata.author?.title}</span>
  </section>
  {
    post.metadata.cover_image && (
      <Image
        src={post.metadata.cover_image.imgix_url}
        format="webp"
        width={1200}
        height={675}
        aspectRatio={16 / 9}
        quality={50}
        alt={`Cover image for the blog ${post.title}`}
        class={'my-12 rounded-md shadow-lg'}
      />
    )
  }
  <div set:html={post.metadata.content} />
</article>