Astro + Partytown

Patterns for offloading third-party scripts to a web worker for better performance.

Why Partytown?

Third-party scripts (analytics, ads, chat widgets) block the main thread and slow page interactivity. Partytown runs them in a web worker, keeping the main thread free.

Setup

npx astro add partytown

// astro.config.mjs
import partytown from '@astrojs/partytown';

export default defineConfig({
  integrations: [
    partytown({
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});

Key Concepts

Scripts use type="text/partytown" and is:inline to run in the web worker. The forward array tells Partytown which functions to proxy from main thread to worker.

Forward Configuration

partytown({
  config: {
    forward: [
      'dataLayer.push',      // Google Analytics/GTM
      'fbq',                 // Facebook Pixel
      'gtag',                // Google gtag
      '_hsq.push',           // HubSpot
    ],
  },
}),

When integrating GA4, GTM, or Facebook Pixel, read references/analytics-integration-examples.md for complete setup snippets with Partytown.

When implementing custom events, conditional loading, or cookie consent, read references/analytics-integration-examples.md for React component events, production-only loading, and consent patterns.

When debugging Partytown issues (scripts not running, CORS errors), read references/analytics-integration-examples.md for troubleshooting steps.

Quick Reference

Key Attributes