@astrojs/partytown

Эта интеграция Astro включает Partytown в вашем проекте Astro.

Зачем Astro Partytown

Partytown - это ленивая библиотека, которая помогает переносить ресурсоемкие скрипты в web worker и разгружать основной поток.

Если вы используете сторонние скрипты для аналитики, рекламы и т.п., 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

Затем примените интеграцию к вашему файлу astro.config.*, используя свойство integrations:

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 перехватывает этот запрос.

Конфигурация

Чтобы настроить эту интеграцию, передайте объект config в вызов функции partytown() в astro.config.mjs.

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

Это соответствует объекту конфигурации Partytown: все опции можно задать в partytown.config. На этой странице описаны некоторые распространенные варианты для проектов Astro.

Включение режима отладки

Partytown поставляется с режимом debug. Включите или выключите его, передав true или false в config.debug. Если режим debug включен, он будет выводить подробные логи в консоль браузера.

Если этот параметр не задан, режим debug будет включен по умолчанию в режиме dev или preview.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Пример: отключить режим отладки.
      config: { debug: false },
    }),
  ],
});

Проброс переменных

Сторонние скрипты обычно добавляют переменные в объект window, чтобы вы могли взаимодействовать с ними по всему сайту. Но когда скрипт загружается в web worker, у него нет доступа к глобальному объекту window.

Чтобы решить это, Partytown может “патчить” переменные в глобальный window и пробрасывать их в нужный скрипт.

Укажите, какие переменные пробрасывать, с помощью опции config.forward. Подробнее в документации Partytown.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Пример: пробрасывать событие dataLayer.push.
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

Проксирование запросов

Некоторые сторонние скрипты могут требовать проксирования через config.resolveUrl(), который выполняется внутри service worker. Вы можете задать эту опцию так, чтобы она проверяла 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. Для этого можно задать resolveUrl() на window.partytown, а не в конфигурации интеграции:

---
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;
    },
  };
`} />