@astrojs/ partytown

v2.1.4 GitHub npm 변경 로그

이 Astro 통합은 Astro 프로젝트에서 Partytown을 활성화합니다.

왜 Astro Partytown인가?

Partytown은 리소스 집약적인 스크립트를 웹 워커 및 메인 스레드 외부로 재배치하는 데 도움이 되는 지연 로드 라이브러리입니다.

분석이나 광고와 같은 작업에 타사 스크립트를 사용하는 경우 Partytown은 사이트 속도를 저하시키지 않도록 하는 좋은 방법입니다.

Astro Partytown 통합은 Partytown을 설치하고 모든 페이지에서 활성화되었는지 확인합니다.

설치

Astro에는 공식 통합 설정을 자동화하는 astro add 명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.

새 터미널 창에서 다음 명령 중 하나를 실행합니다.

npx astro add partytown

pnpm astro add partytown

yarn astro add partytown

문제가 발생하면 GitHub에서 언제든지 보고하고 아래 수동 설치 단계를 시도해 보세요.

수동 설치

먼저 @astrojs/partytown 패키지를 설치하세요.

npm install @astrojs/partytown

pnpm add @astrojs/partytown

yarn add @astrojs/partytown

그런 다음 integrations 속성을 사용하여 astro.config.* 파일에 통합을 적용합니다.

import { defineConfig } from 'astro/config';
import partytown from '@astrojs/partytown';

export default defineConfig({
  // ...
  integrations: [partytown()],
});

사용하기

Partytown은 구성 없이 사용할 준비가 되어 있어야 합니다. 사이트에 기존 타사 스크립트가 있는 경우 type="text/partytown" 속성을 추가해 보세요.

<script type="text/partytown" src="fancy-analytics.js"></script>

브라우저 개발 도구에서 “Network” 탭을 열면 partytown 프록시가 이 요청을 가로채는 것을 볼 수 있습니다.

구성

이 통합을 구성하려면 astro.config.mjs 파일의 partytown() 함수 호출에 ‘config’ 객체를 전달하세요.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      config: {
        // 옵션은 여기에 추가합니다.
      },
    }),
  ],
});

이는 Partytown 구성 객체를 미러링합니다.

config.debug

Partytown에는 debug 모드가 포함되어 있습니다. config.debug에 true 또는 false를 전달하여 활성화하거나 비활성화합니다. debug 모드가 활성화되면 브라우저 콘솔에 자세한 로그가 출력됩니다.

기본적으로 이 옵션을 설정하지 않으면 dev 모드나 preview 모드에서 디버그 모드가 켜집니다.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 예: 디버그 모드를 비활성화합니다.
      config: { debug: false },
    }),
  ],
});

config.forward

타사 스크립트는 일반적으로 window 객체에 변수를 추가하므로 사이트 전체에서 해당 객체와 통신할 수 있습니다. 그러나 웹 워커에 스크립트가 로드되면 해당 전역 window 객체에 액세스할 수 없습니다.

이 문제를 해결하기 위해 Partytown은 전역 window 객체에 변수를 “patch”하고 이를 적절한 스크립트로 전달할 수 있습니다.

config.forward 옵션을 사용하여 전달할 변수를 지정할 수 있습니다. Partytown 문서에서 자세히 알아보세요.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 예: dataLayer.push를 forwarding-event로 추가합니다.
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

config.resolveUrl

일부 타사 스크립트는 서비스 워커에서 실행되는 config.resolveUrl()을 통한 프록시가 필요할 수 있습니다. 이 구성 옵션을 설정하여 특정 URL을 확인하고, 대신 프록시된 URL을 선택적으로 반환할 수 있습니다.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // 예시: Facebook의 분석 스크립트 프록시
      config: {
        resolveUrl: (url) => {
          const proxyMap = {
            "connect.facebook.net": "my-proxy.com"
          }
          url.hostname = proxyMap[url.hostname] || url.hostname;
          return url;
        },
      }
    }),
  ],
});

그러나 config 객체가 클라이언트로 전송될 때 직렬화되므로 구성에 전달되는 함수에 대한 몇 가지 제한 사항이 적용됩니다.

함수 범위 밖에 있는 것을 참조할 수 없습니다.
오직 JavaScript로만 작성할 수 있습니다.

일부 고급 사용 사례에서는 Partytown을 초기화하는 동안 이 함수에 데이터를 전달해야 할 수도 있습니다. 이렇게 하려면 통합 구성 대신 window.partytown에서 resolveUrl()을 설정하면 됩니다.

---
const proxyMap = {
  "connect.facebook.net": "my-proxy.com"
};
---

<script is:inline set:html={`
  window.partytown = {
    resolveUrl: (url) => {
      const proxyMap = ${JSON.stringify(proxyMap)};
      url.hostname = proxyMap[url.hostname] || url.hostname;
      return url;
    },
  };
`} />