@astrojs/ partytown

This Astro integration enables Partytown in your Astro project.

Why Astro Partytown

Partytown is a lazy-loaded library to help relocate resource intensive scripts into a web worker, and off of the main thread.

If you’re using third-party scripts for things like analytics or ads, Partytown is a great way to make sure that they don’t slow down your site.

The Astro Partytown integration installs Partytown for you and makes sure it’s enabled on all of your pages.

Installation

Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

Run one of the following commands in a new terminal window.

npx astro add partytown

pnpm astro add partytown

yarn astro add partytown

If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

Manual Install

First, install the @astrojs/partytown package:

npm install @astrojs/partytown

pnpm add @astrojs/partytown

yarn add @astrojs/partytown

Then, apply the integration to your astro.config.* file using the integrations property:

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

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

Usage

Partytown should be ready to go with zero config. If you have an existing 3rd party script on your site, try adding the type="text/partytown" attribute:

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

If you open the “Network” tab from your browser’s dev tools, you should see the partytown proxy intercepting this request.

Configuration

To configure this integration, pass a ‘config’ object to the partytown() function call in astro.config.mjs.

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

This mirrors the Partytown config object.

config.debug

Partytown ships with a debug mode; enable or disable it by passing true or false to config.debug. If debug mode is enabled, it will output detailed logs to the browser console.

If this option isn’t set, debug mode will be on by default in dev or preview mode.

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

config.forward

Third-party scripts typically add variables to the window object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn’t have access to that global window object.

To solve this, Partytown can “patch” variables to the global window object and forward them to the appropriate script.

You can specify which variables to forward with the config.forward option. Read more in Partytown’s documentation.

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