프레임워크 컴포넌트

선호하는 컴포넌트 프레임워크를 희생하지 않고 Astro 웹사이트를 구축하세요. 선택한 UI 프레임워크를 사용하여 Astro 아일랜드을 만드세요.

공식 UI 프레임워크 통합

Astro는 React, Preact, Svelte, Vue, SolidJS, AlpineJS, Lit 공식 통합이 포함되어 있습니다.

통합 디렉터리에서 더 많은 커뮤니티에서 관리하는 프레임워크 통합 (예: Angular, Qwik, Elm)을 찾아보세요.

UI 프레임워크

통합 설치

이러한 Astro 통합 중 하나 이상을 프로젝트에 설치하고 구성할 수 있습니다.

Astro 통합 설치 및 구성에 대한 자세한 내용은 통합 안내서를 참조하세요.

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

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를 이용하여 대화형(하이드레이션)으로 만들 수 있습니다. 이는 컴포넌트의 자바스크립트가 브라우저로 전송되는 시기를 결정하는 컴포넌트 속성입니다.

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 페이지를 참조하세요.

프레임워크 혼합하기

동일한 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 대해 자세히 알아보기

GitHub Issue 생성

의견 보내기

프레임워크 컴포넌트

공식 UI 프레임워크 통합

UI 프레임워크

@astrojs/alpinejs

@astrojs/lit

@astrojs/preact

@astrojs/react

@astrojs/solid⁠-⁠js

@astrojs/svelte

@astrojs/vue