Astro와 React 아일랜드 설정

Astro 프로젝트를 처음 생성할 때는 npx create astro@latest를 사용합니다. 이 명령은 템플릿, TypeScript 설정, 패키지 관리자를 선택할 수 있는 대화형 마법사를 실행합니다. Astro는 빈 템플릿, 블로그 템플릿, 문서 템플릿을 비롯한 여러 시작 템플릿을 지원합니다.

Astro 통합은 프로젝트에 프레임워크 지원을 추가합니다. npx astro add react를 실행하면 @astrojs/react, react, react-dom을 자동으로 설치하고, React 통합을 포함하도록 astro.config.mjs를 업데이트합니다. 전체 설정에 명령 하나만 필요합니다.

.astro 파일은 Astro의 컴포넌트 형식입니다. 프런트매터 섹션(--- 구분선 사이의 JavaScript)과 템플릿 섹션으로 구성됩니다. Astro 파일은 기본적으로 정적 HTML을 출력하므로, 클라이언트 지시어를 명시적으로 추가하지 않는 한 브라우저로 JavaScript가 전송되지 않습니다.

Astro 파일에서 React 컴포넌트를 가져올 때는 표준 ES 모듈 구문을 사용합니다. import Counter from './Counter.jsx'와 같이 작성합니다. 클라이언트 지시어가 없으면 Astro는 React 컴포넌트를 서버에서 정적 HTML로 렌더링하고 해당 HTML을 브라우저로 전송하므로, 이 컴포넌트에 제공되는 JavaScript는 전혀 없습니다.

Astro 템플릿의 컴포넌트 태그에 client:visible을 추가하면 아일랜드로 바뀝니다. <Counter client:visible />와 같이 작성합니다. 이제 Astro는 Counter의 JavaScript를 전송하고, 컴포넌트가 화면에 들어올 때 하이드레이션하여 상호작용 가능하게 만듭니다. 지시어가 없으면 정적 HTML로 유지됩니다.

Astro 아일랜드로 사용하는 React 컴포넌트는 표준 React로 작성합니다. 훅, 상태, 효과 및 모든 React 라이브러리를 사용할 수 있습니다. React 컴포넌트 자체에는 Astro 전용 API가 없습니다. 아일랜드 경계는 컴포넌트 코드 내부가 아니라 Astro 템플릿에서 정의됩니다.

각 아일랜드 인스턴스는 독립적인 React 트리입니다. 같은 페이지에 있는 두 개의 Counter 아일랜드는 상태를 공유하지 않습니다. 상태를 공유해야 한다면 세 가지 방법이 있습니다. 하나의 아일랜드로 합치거나, 직렬화할 수 있는 상태에 URL 검색 매개변수를 사용하거나, nanostores와 같은 공유 상태 라이브러리를 사용하는 방법입니다.

@nanostores/react 라이브러리는 모든 아일랜드가 구독할 수 있는 가벼운 원자를 제공합니다. 한 아일랜드가 나노스토어 원자에 값을 쓰면 다른 아일랜드가 그 값을 읽습니다. 나노스토어는 특정 프레임워크에 종속되지 않으므로, 같은 페이지의 React 아일랜드와 Vue 아일랜드 사이에서도 이 패턴을 사용할 수 있습니다.

Astro 콘텐츠 컬렉션은 Markdown 및 MDX 파일을 타입 안전하게 관리하는 방법을 제공합니다. Zod로 컬렉션 스키마를 정의하고, src/content/에 Markdown 파일을 배치하면 Astro가 타입이 완전히 지정된 쿼리 함수를 생성합니다. 블로그 게시물, 문서, 제품 페이지에 사용하는 표준 패턴입니다.

astro build를 실행하면 정적 HTML 파일이 들어 있는 dist/ 폴더가 생성됩니다. Astro는 각 페이지에 대해 서버에서 렌더링된 콘텐츠가 포함된 HTML 파일과 해당 페이지의 아일랜드에 필요한 JavaScript 번들만 출력합니다. 아일랜드가 없는 페이지에서는 JavaScript가 전혀 출력되지 않습니다.

정적 출력물은 서버 없이 모든 CDN(Netlify, Vercel, Cloudflare Pages)에 배포할 수 있습니다. 서버 측 렌더링이 필요한 경우(동적 경로, API 엔드포인트) Astro는 Node.js, Vercel Edge, Cloudflare Workers, Deno용 SSR 어댑터를 지원합니다. 두 방식 모두에서 아일랜드는 동일하게 작동합니다.

가져온 React 컴포넌트를 Astro 템플릿에서 클라이언트의 상호작용 컴포넌트로 만들려면 어떤 최소 변경이 필요합니까?

npx astro add react를 사용하여 Astro를 React와 함께 설정합니다. Astro 파일은 기본적으로 정적이며, React 컴포넌트 태그에 client: 지시어를 추가하면 하이드레이션되는 아일랜드로 바뀝니다. React 컴포넌트는 Astro 전용 API가 없는 표준 React 컴포넌트입니다. 상태는 아일랜드별로 격리되며, nanostores를 사용하면 아일랜드 간 통신이 가능합니다. 빌드 결과에는 필요한 아일랜드 JavaScript만 포함된 정적 HTML이 출력됩니다.