프레임워크 컴포넌트

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

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}입니다.

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

프레임워크 혼합

동일한 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> 태그를 사용하여 브라우저 전역 범위에서 실행되는 자바스크립트를 보낼 수 있습니다.

Astro 컴포넌트의 클라이언트 측 <script> 태그 대해 자세히 알아보기

GitHub Issue 생성

의견 보내기

프레임워크 컴포넌트

공식 UI 프레임워크 통합

UI 프레임워크

@astrojs/alpinejs

@astrojs/lit

@astrojs/preact

@astrojs/react

@astrojs/solid⁠-⁠js

@astrojs/svelte

@astrojs/vue