astro/packages/integrations/partytown/README.md

@astrojs/partytown 🎉

This Astro integration enables Partytown in your Astro project.

• Why Astro Partytown
• Installation
• Usage
• Configuration
• Examples
• Troubleshooting
• Contributing
• Changelog

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

Quick Install

The experimental astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.

# Using NPM
npx astro add partytown
# Using Yarn
yarn astro add partytown
# Using PNPM
pnpx astro add partytown

Then, restart the dev server by typing CTRL-C and then npm run astro dev in the terminal window that was running Astro.

Because this command is new, it might not properly set things up. If that happens, feel free to log an issue on our GitHub and try the manual installation steps below.

Manual Install

First, install the @astrojs/partytown package using your package manager. If you're using npm or aren't sure, run this in the terminal:

npm install @astrojs/partytown

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

astro.config.mjs

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

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

Then, restart the dev server.

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 src="fancy-analytics.js"></script>
+  <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.

astro.config.mjs

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

This mirrors the Partytown config object, but only debug and forward are exposed by this integration.

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.

astro.config.mjs

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.

astro.config.mjs

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

Examples

• The integrations playground template comes with Astro Partytown installed, with a demo script that shows how Partytown moves intensive operations off of the main thread.

• Browse projects with Astro Partytown on GitHub for more examples!

Troubleshooting

Contributing

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!

Changelog