프레임워크 컴포넌트

선호하는 컴포넌트 프레임워크를 그대로 유지하면서 Astro 웹사이트를 구축할 수 있습니다.

Astro는 React, Preact, Svelte, Vue, SolidJS, AlpineJS, Lit 등 다양한 인기 프레임워크를 지원합니다.

통합 설치

Astro는 React, Preact, Svelte, Vue, SolidJS, AlpineJS 및 Lit에 대한 optional integrations (EN)과 함께 제공됩니다. 프로젝트에서 하나 또는 여러 개의 Astro 통합을 설치하고 설정할 수 있습니다.

⚙️ Astro 통합 설치 및 설정에 대한 자세한 내용은 Integrations Guide (EN)를 참조하세요.

⚙️ 선택한 프레임워크의 예시를 확인하고 싶다면, astro.new를 방문하여 프레임워크 템플릿 중 하나를 선택하세요.

프레임워크 컴포넌트 사용하기

Astro 컴포넌트와 마찬가지로 자바스크립트 프레임워크 컴포넌트를 Astro 페이지, 레이아웃, 컴포넌트에서 사용할 수 있습니다! 모든 컴포넌트는 /src/components에 모아두거나 원하는 대로 구성할 수 있습니다.

프레임워크 컴포넌트를 사용하려면 Astro 컴포넌트 스크립트에서 상대 경로를 지정하여 가져옵니다. 그리고 컴포넌트 템플릿에서 다른 컴포넌트, HTML 요소, JSX와 같은 표현식과 함께 사용합니다.

---
import MyReactComponent from '../components/MyReactComponent.jsx';
---
<html>
  <body>
    <h1>Astro 안에서 React 컴포넌트를 직접 사용하세요!</h1>
    <MyReactComponent />
  </body>
</html>

기본적으로 프레임워크 컴포넌트는 서버에서 정적 HTML로 렌더링 됩니다. 이는 비대화형 컴포넌트를 템플릿화하는데 유용하며, 필요하지 않은 자바스크립트를 클라이언트에 전송하는 것을 방지합니다.

인터랙티브 컴포넌트 하이드레이션하기

프레임워크 컴포넌트는 client:* directive (EN)를 이용하여 대화형(하이드레이션)으로 만들 수 있습니다. 이는 컴포넌트의 자바스크립트가 브라우저로 전송되는 시기를 결정하는 컴포넌트 속성입니다.

client:only를 제외한 모든 클라이언트 지시문을 사용하면 컴포넌트는 먼저 서버에서 렌더링 되어 정적 HTML을 생성합니다. 자바스크립트 컴포넌트는 지시어에 따라 브라우저로 전송됩니다. 이후 컴포넌트가 하이드레이트 되어 인터랙티브하게 됩니다.

---
// 예: 브라우저에서 컴포넌트 하이드레이션하기
import InteractiveButton from '../components/InteractiveButton.jsx';
import InteractiveCounter from '../components/InteractiveCounter.jsx';
import InteractiveModal from "../components/InteractiveModal.svelte"
---
<!-- 이 컴포넌트의 자바스크립트는 페이지 로딩 시에 가져옵니다. -->
<InteractiveButton client:load />

<!-- 이 컴포넌트의 자바스크립트는 사용자가 스크롤하여 컴포넌트가 페이지에 표시될 때까지 클라이언트에게 전송되지 않습니다. -->
<InteractiveCounter client:visible />

<!-- 이 컴포넌트는 서버에서 렌더링되지 않고 페이지 로딩 시 클라이언트에서 렌더링됩니다. -->
<InteractiveModal client:only="svelte" />

컴포넌트를 렌더링하는 데 필요한 자바스크립트 프레임워크(React, Svelte 등)는 컴포넌트 자체의 자바스크립트와 함께 브라우저로 전송됩니다. 페이지의 여러 컴포넌트가 동일한 프레임워크를 사용하는 경우, 프레임워크는 한 번만 전송됩니다.

사용 가능한 하이드레이션 지시어

UI 프레임워크 컴포넌트에서 사용할 수 있는 하이드레이션 지시어는 client:load, client:idle, client:visible, client:media={QUERY}, client:only={FRAMEWORK}입니다.

📚 하이드레이션 지시어에 대한 자세한 설명과 사용법은 directives reference (EN) 페이지를 참조하세요.

프레임워크 혼합하기

동일한 Astro 컴포넌트 내에서 여러 프레임워크에서 만든 컴포넌트를 가져와 렌더링할 수 있습니다.

---
// 예: 한 페이지에 여러 프레임워크의 구성요소를 혼합하는 경우
import MyReactComponent from '../components/MyReactComponent.jsx';
import MySvelteComponent from '../components/MySvelteComponent.svelte';
import MyVueComponent from '../components/MyVueComponent.vue';
---
<div>
  <MySvelteComponent />
  <MyReactComponent />
  <MyVueComponent />
</div>

프레임워크 컴포넌트에 Props 전달하기

Astro 컴포넌트에서 프레임워크 컴포넌트로 props를 전달할 수 있습니다.

---
import TodoList from '../components/TodoList.jsx';
import Counter from '../components/Counter.svelte';
---
<div>
  <TodoList initialTodos={["learn Astro", "review PRs"]} />
  <Counter startingCount={1} />
</div>

프레임워크 컴포넌트에 자식 요소 전달하기

Astro 컴포넌트에서는 프레임워크 컴포넌트에 자식 요소를 전달할 수 있습니다. 각 프레임워크마다 이러한 자식 요소를 참조하는 고유한 패턴이 있는데, React, Preact, Solid는 children이라는 특별한 속성을 사용하고, Svelte와 Vue는 <slot />라는 요소를 사용합니다.

---
import MyReactSidebar from '../components/MyReactSidebar.jsx';
---
<MyReactSidebar>
  <p>텍스트와 버튼이 있는 사이드바입니다.</p>
</MyReactSidebar>

또한, 명명된 슬롯을 사용하여 특정 하위 요소를 그룹화할 수 있습니다.

React, Preact, Solid에서 이러한 슬롯은 최상위 속성으로 변환되며, kebab-case를 사용하는 슬롯 이름은 camelCase로 변환됩니다.

---
import MySidebar from '../components/MySidebar.jsx';
---
<MySidebar>
  <h2 slot="title">Menu</h2>
  <p>텍스트와 버튼이 있는 사이드바입니다.</p>
  <ul slot="social-links">
    <li><a href="https://twitter.com/astrodotbuild">Twitter</a></li>
    <li><a href="https://github.com/withastro">GitHub</a></li>
  </ul>
</MySidebar>

export default function MySidebar(props) {
  return (
    <aside>
      <header>{props.title}</header>
      <main>{props.children}</main>
      <footer>{props.socialLinks}</footer>
    </aside>
  )
}

Svelte와 Vue에서 이러한 슬롯은 <slot> 요소에 name 속성을 붙여 참조할 수 있습니다. 또한 kebab-case를 사용한 슬롯 이름은 그대로 유지됩니다.

<aside>
  <header><slot name="title" /></header>
  <main><slot /></main>
  <footer><slot name="social-links" /></footer>
</aside>

프레임워크 컴포넌트 중첩하기

Astro 파일 내에서는 프레임워크 컴포넌트의 자식 요소도 하이드레이션된 컴포넌트로 만들 수 있습니다. 즉, 프레임워크의 모든 컴포넌트를 재귀적으로 중첩할 수 있습니다.

---
import MyReactSidebar from '../components/MyReactSidebar.jsx';
import MyReactButton from '../components/MyReactButton.jsx';
import MySvelteButton from '../components/MySvelteButton.svelte';
---

<MyReactSidebar>
  <p>텍스트와 버튼이 있는 사이드바입니다.</p>
  <div slot="actions">
    <MyReactButton client:idle />
    <MySvelteButton client:idle />
  </div>
</MyReactSidebar>

이를 통해 원하는 자바스크립트 프레임워크로 전체 ‘앱’을 구축하고 상위 컴포넌트를 통해 Astro의 페이지로 렌더링할 수 있습니다.

프레임워크 컴포넌트 중 Astro 컴포넌트를 사용할 수 있나요?

UI 프레임워크 컴포넌트는 해당 프레임워크의 ‘아일랜드 (섬)‘가 됩니다. 이러한 컴포넌트는 해당 프레임워크의 유효한 코드로서 자체 가져오기 또는 패키지를 사용하여 완전히 작성해야 하며, UI 프레임워크 컴포넌트(예: .jsx 또는 .svelte) 내에서 .astro 컴포넌트를 가져올 수 없습니다.

하지만 Astro의 <slot /> 패턴을 이용하여 Astro 컴포넌트가 생성한 정적 콘텐츠를 .astro 컴포넌트 내에서 프레임워크 컴포넌트에 자식 요소로 전달할 수 있습니다.

---
import MyReactComponent from  '../components/MyReactComponent.jsx';
import MyAstroComponent from '../components/MyAstroComponent.astro';
---
<MyReactComponent>
  <MyAstroComponent slot="name" />
</MyReactComponent>

Astro 컴포넌트에 하이드레이션을 할 수 있나요?

client: 지시어를 사용하여 Astro 컴포넌트에 하이드레이션을 시도하면 오류가 발생합니다.

Astro 컴포넌트는 클라이언트 측 런타임이 없는 HTML 전용 템플릿 컴포넌트입니다. 하지만 Astro 컴포넌트 템플릿에서 <script> 태그를 사용하여 브라우저 전역 범위에서 실행되는 자바스크립트를 보낼 수 있습니다.

📚 client-side <script> tags in Astro components (EN) 대해 자세히 알아보기

GitHub Issue 생성

Send us feedback