@astrojs/ partytown

Esta integración de Astro habilita Partytown en tu proyecto de Astro.

Por qué Astro Partytown

Partytown es una biblioteca de carga diferida para ayudar a reubicar scripts que consumen muchos recursos en un web worker, y fuera del hilo principal.

Si estás utilizando scripts de terceros para cosas como analíticas o anuncios, Partytown es una excelente manera de asegurarse de que no ralenticen tu sitio.

La integración Astro Partytown instala Partytown por ti y se asegura de que esté habilitado en todas tus páginas.

Instalación

Astro incluye un comando astro add para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes instalar las integraciones manualmente en su lugar.

Ejecuta uno de los siguientes comandos en una nueva ventana de terminal.

npx astro add partytown

pnpm astro add partytown

yarn astro add partytown

Si tienes algún problema, no dudes en informarnos en GitHub e intenta los pasos de instalación manual a continuación.

Instalación manual

Primero, instala el paquete @astrojs/partytown:

npm install @astrojs/partytown

pnpm add @astrojs/partytown

yarn add @astrojs/partytown

Luego, aplica la integración a tu archivo astro.config.* usando la propiedad integrations:

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

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

Uso

Partytown debería estar listo para funcionar sin ninguna configuración. Si tienes un script de terceros existente en tu sitio, intenta añadir el atributo type="text/partytown":

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

Si abres la pestaña «Red» desde las herramientas de desarrollo de tu navegador, deberías ver que el proxy de partytown intercepta esta solicitud.

Configuración

Para configurar esta integración, pasa un objeto 'config' a la llamada de la función partytown() en astro.config.mjs.

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

Esto refleja el objeto de configuración de Partytown y todas las opciones se pueden configurar en partytown.config. En esta página se describen algunas opciones de configuración comunes para los proyectos de Astro.

Habilitar el modo de depuración

Partytown incluye un modo de depuración; habilítalo o deshabilítalo pasando true o false a config.debug. Si el modo de depuración está habilitado, mostrará registros detallados en la consola del navegador.

Si esta opción no está configurada, el modo de depuración estará activado por defecto en el modo dev o preview.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: Disable debug mode.
      config: { debug: false },
    }),
  ],
});

Reenvío de variables

Los scripts de terceros normalmente añaden variables al objeto window para que puedas comunicarte con ellos en todo tu sitio. Pero cuando un script se carga en un web-worker, no tiene acceso a ese objeto window global.

Para solucionar esto, Partytown puede "parchear" variables al objeto window global y reenviarlas al script correspondiente.

Puedes especificar qué variables reenviar con la opción config.forward. Lee más en la documentación de Partytown.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: Add dataLayer.push as a forwarding-event.
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

Proxy de solicitudes

Algunos scripts de terceros pueden requerir hacer proxy a través de config.resolveUrl(), que se ejecuta dentro del service worker. Puedes configurar esta opción para verificar una URL específica y, opcionalmente, devolver una URL con proxy en su lugar:

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: proxy Facebook's analytics script
      config: {
        resolveUrl: (url) => {
          const proxyMap = {
            "connect.facebook.net": "my-proxy.com"
          }
          url.hostname = proxyMap[url.hostname] || url.hostname;
          return url;
        },
      }
    }),
  ],
});

Sin embargo, dado que el objeto config se serializa cuando se envía al cliente, se aplican algunas limitaciones a las funciones pasadas a tu configuración:

Las funciones no pueden hacer referencia a nada fuera del ámbito de la función.
Las funciones solo se pueden escribir en JavaScript.

En algunos casos de uso avanzado, es posible que debas pasar datos a esta función mientras se inicializa Partytown. Para hacerlo, puedes configurar resolveUrl() en window.partytown en lugar de la configuración de la integración:

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