@astrojs/ lit
이 Astro 통합 을 통해 Lit 맞춤 요소에 대한 서버 측 렌더링 및 클라이언트 측 하이드레이션이 가능해졌습니다.
Astro에는 공식 통합 설정을 자동화하는 astro add 명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.
@astrojs/lit을 설치하려면 프로젝트 디렉터리에서 다음을 실행하고 프롬프트를 따르세요.
npx astro add litpnpm astro add lityarn astro add lit문제가 발생하면 GitHub에서 언제든지 보고하고 아래 수동 설치 단계를 시도해 보세요.
수동 설치
섹션 제목: 수동 설치먼저 @astrojs/lit 패키지를 설치하세요.
npm install @astrojs/litpnpm add @astrojs/lityarn add @astrojs/lit대부분의 패키지 관리자는 관련 피어 종속성도 설치합니다. Astro를 시작할 때 “Cannot find package ‘lit’” (또는 이와 유사한) 경고가 표시되면 lit 및 @webcomponents/template-shadowroot를 설치해야 합니다.
npm install lit @webcomponents/template-shadowrootpnpm add lit @webcomponents/template-shadowrootyarn add lit @webcomponents/template-shadowroot그런 다음 integrations 속성을 사용하여 astro.config.* 파일에 통합을 적용합니다.
import { defineConfig } from 'astro/config';import lit from '@astrojs/lit';
export default defineConfig({ // ... integrations: [lit()],});시작하기
섹션 제목: 시작하기Astro에서 첫 번째 Lit 컴포넌트를 사용하려면 UI 프레임워크 문서로 이동하세요. 이는 다음을 설명합니다.
- 📦 프레임워크 컴포넌트가 로드되는 방식,
- 💧 클라이언트 측 하이드레이션 옵션
- 🤝 프레임워크를 함께 혼합하고 중첩할 수 있는 기회
Astro에서 Lit 컴포넌트를 작성하고 가져오는 방법은 다음과 같습니다.
import { LitElement, html } from 'lit';
export class MyElement extends LitElement { render() { return html`<p>Hello world! From my-element</p>`; }}
customElements.define('my-element', MyElement);이제 Astro 프론트매터를 통해 컴포넌트를 가져올 준비가 되었습니다.
---import { MyElement } from '../components/my-element.js';---
<MyElement />실험적 Decorators
섹션 제목: 실험적 DecoratorsLit의 실험적 Decorators를 사용하려면 tsconfig.json 파일에 다음을 추가하세요.
{ "compilerOptions": { "experimentalDecorators": true, }}이를 통해 @customElement 및 @state와 같은 실험적 Decorators를 사용하여 맞춤 속성을 등록하고 Lit 컴포넌트에 상태 속성을 정의할 수 있습니다.
import { LitElement, html } from "lit";import { customElement, state } from "lit/decorators.js";
@customElement("my-element")export class MyElement extends LitElement { @state() name = "my-element";
override render() { return html`<p>Hello world! From ${this.name}</p>`; }}폴리필 및 하이드레이션
섹션 제목: 폴리필 및 하이드레이션렌더러는 Declarative Shadow DOM이 없는 브라우저에서 지원하기 위해 적절한 폴리필 추가를 자동으로 처리합니다. 폴리필은 약 1.5kB입니다. 브라우저가 Declarative Shadow DOM을 지원하는 경우 250바이트 미만이 로드됩니다 (기능 감지 지원을 위해).
하이드레이션도 자동으로 처리됩니다. Astro가 지원하는 다른 라이브러리와 마찬가지로 client:load, client:idle, client:visible과 같은 동일한 하이드레이션 지시어를 사용할 수 있습니다.
---import { MyElement } from '../components/my-element.js';---
<MyElement client:visible />위 내용은 사용자가 요소를 뷰포트로 스크롤한 경우에만 요소의 JavaScript를 로드합니다. 서버 렌더링이므로 버벅거림이 표시되지 않습니다. 투명하게 로딩되고 하이드레이션 됩니다.
문제 해결
섹션 제목: 문제 해결도움이 필요하시면 Discord의 #support 채널을 확인하세요. 우리의 친절한 지원팀 멤버들이 도와드리겠습니다!
통합에 대한 자세한 내용은 Astro 통합 문서를 확인하실 수도 있습니다.
일반적인 문제는 다음과 같습니다.
브라우저 전역 객체
섹션 제목: 브라우저 전역 객체Lit 통합의 SSR은 전역 환경에 몇 가지 브라우저 전역 속성을 추가하여 작동합니다. 추가되는 속성 중 일부에는 window, document, location이 포함됩니다.
이러한 전역 변수는 실제로 서버에서 실행 중일 때 브라우저에서 실행 중임을 감지하기 위해 이러한 변수의 존재를 사용할 수 있는 다른 라이브러리를 방해할 수 있습니다. 이로 인해 해당 라이브러리에 버그가 발생할 수 있습니다.
이로 인해 Lit 통합은 이러한 유형의 라이브러리와 호환되지 않을 수 있습니다. 도움이 될 수 있는 한 가지는 Lit가 다른 통합을 방해할 때 통합 순서를 변경하는 것입니다.
import { defineConfig } from 'astro/config'; import vue from '@astrojs/vue'; import lit from '@astrojs/lit';
export default defineConfig({ integrations: [vue(), lit()] integrations: [lit(), vue()] });올바른 순서는 문제의 근본 원인에 따라 다를 수 있습니다. 그러나 이것이 모든 문제를 해결한다고 보장할 수는 없으며 이로 인해 Lit 통합을 사용하는 경우 일부 라이브러리를 사용할 수 없습니다.
엄격한 패키지 관리자
섹션 제목: 엄격한 패키지 관리자pnpm과 같은 엄격한 패키지 관리자를 사용하면 사이트를 실행할 때 ReferenceError: module is not defined과 같은 오류가 발생할 수 있습니다. 이 문제를 해결하려면 .npmrc 파일을 사용하여 Lit 종속성을 끌어올리세요.
public-hoist-pattern[]=*lit*제한 사항
섹션 제목: 제한 사항Lit 통합은 몇 가지 제한 사항이 있는 @lit-labs/ssr을 통해 구동됩니다. 자세한 내용은 제한 사항 문서를 참조하세요.
Astro는 Lit 컴포넌트용 IntelliSense를 지원하지 않습니다.
