Astro 5 완벽 가이드 — Content Layer API와 서버 아일랜드

Content Layer API

Astro 5의 Content Layer API는 기존 Content Collections를 확장하여 로컬 마크다운 파일뿐 아니라 CMS, API, 데이터베이스 등 외부 소스에서 콘텐츠를 가져와 동일한 인터페이스로 사용할 수 있게 한다. 로더(Loader) 함수를 정의하면 원하는 소스에서 데이터를 가져오고 Zod 스키마로 검증한 뒤 빌드 타임에 캐시한다. 증분 빌드를 지원하여 변경된 항목만 다시 가져오므로 대규모 콘텐츠 사이트에서 빌드 속도가 크게 향상된다.

// src/content/config.ts
import { defineCollection, z } from 'astro:content'
import { glob } from 'astro/loaders'

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title:       z.string(),
    publishedAt: z.coerce.date(),
    tags:        z.array(z.string()).default([]),
  }),
})

export const collections = { blog }

Server Islands로 부분 동적 렌더링

Server Islands는 정적으로 생성된 페이지 내에 동적으로 서버 렌더링되는 컴포넌트를 삽입하는 기능이다. server:defer 지시어를 컴포넌트에 추가하면 해당 컴포넌트만 요청 시 서버에서 렌더링되고, 나머지 페이지는 CDN에서 즉시 제공된다. 로그인 상태에 따른 메뉴 변화, 사용자별 추천 콘텐츠, 실시간 재고 정보처럼 개인화가 필요한 부분에 적합하다. Next.js의 Partial Prerendering과 유사한 개념이지만 Astro의 MPA 기반으로 구현된다.

Astro Actions — 타입 안전 서버 함수

Astro Actions는 Next.js의 Server Actions에 대응하는 Astro의 서버 함수 기능이다. defineAction으로 입력 스키마와 핸들러를 선언하면, 클라이언트에서 타입 안전하게 서버 함수를 호출할 수 있다. Zod 스키마로 입력 유효성 검사가 자동 처리되며, 폼 제출, 데이터 뮤테이션, 파일 업로드 등 다양한 서버 사이드 작업을 구현할 수 있다. actions.blog.like(postId) 형태로 호출하며 반환 타입이 TypeScript로 추론된다.

개선된 View Transitions

Astro 5는 View Transitions API 지원을 더욱 강화하였다. <ClientRouter />(이전의 <ViewTransitions />) 컴포넌트로 활성화하며, 페이지 간 공유 요소 전환, 커스텀 애니메이션, 비지원 브라우저 폴백이 모두 지원된다. 특히 MPA 환경에서 JavaScript 없이도 CSS만으로 공유 요소 전환을 구현할 수 있어, 풀 JavaScript 프레임워크 없이 SPA 수준의 전환 경험을 제공한다.

Astro 4에서 5로 마이그레이션

Astro 4와 5는 대부분 호환되지만 Content Collections API에 변경이 있다. src/content/config.ts에서 컬렉션을 정의하는 방식이 loader 기반으로 바뀌었으며, astro upgrade 명령으로 자동 마이그레이션이 지원된다. 주요 Breaking Change는 image() 헬퍼 변경과 일부 어댑터 API 수정이다. 마이그레이션 가이드를 확인하고 주요 페이지를 테스트한 뒤 배포하는 것을 권장한다.

언제 Astro를 선택해야 하나요

Astro는 콘텐츠 중심의 정적 사이트(블로그, 문서, 마케팅 페이지)에 최적화되어 있다. JavaScript를 최소화하고 첫 페이지 로딩 속도를 극대화하는 것이 목표라면 Astro가 Next.js보다 유리하다. 반면 복잡한 클라이언트 상태 관리, 실시간 데이터, 인증이 필요한 대규모 웹 앱에는 Next.js나 Remix가 더 적합하다. Astro는 React, Vue, Svelte, Solid 컴포넌트를 혼합 사용할 수 있어 기존 자산을 재활용하면서 점진적으로 도입할 수도 있다.