Getting JavaScript Under Control With Partytown

The Problem: A Choked Main Thread

Despite optimizing our own codebase, user interactions were sluggish, especially on mobile. Page loads looked fine on paper, but real user monitoring told a different story: long input delays, especially during first loads and navigation transitions.

What was killing performance was a multitude of third-party scripts that ran on the main thread, blocking user interactions and spiking TTI.

‍

Enter Partytown

Partytown is a JavaScript library that runs third-party scripts in web workers — effectively offloading execution from the main thread. It acts as a proxy between your site and the script origin, allowing safe isolation and better performance.

‍

Moving to Partytown improves speed, responsiveness, and user experience — especially on low-end mobile devices.

‍

Here's the documentation I wrote for using Partytown:

Learning Resources

• [(https://partytown.builder.io/how-does-partytown-work)]
• [(https://www.youtube.com/watch?v=eP6Mti85HeQ)]
• [(https://partytown.builder.io/shopify-os2)]

‍

How Partytown Works

Partytown relies on Web Workers, Service Workers, JavaScript Proxies, and a communication layer between them all.

• [(https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)]
• [(https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)]
• [(https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)]

‍

Partytown Lifecycle

1. Add a 'type="text/partytown"' attribute to the scripts that Partytown will handle.
   • This blocks the browser's main thread from being able to run the code since, technically, it is now no longer designated as JavaScript.
   • The inline Partytown script can now query the scripts that are to be handled by Partytown.
   • The developer can choose exactly which scripts should use Partytown while leaving all the other scripts unchanged.
2. The inline Partytown script then places all of the queried scripts inside a web worker in the browser, offloading the JavaScript off the main thread and leaving the main thread alone to run the critical tasks.
3. When the web worker runs into a line of code that it cannot execute due to an object, it cannot access, such as the DOM or window object, the web worker sends a fetch using an XHR request, 'XMLHttpRequest' to be exact, to the proxy location where the service worker is located. The worker thread is synchronously blocked while it waits for the response, but because it does not block the main thread, the main thread remains free to run the critical tasks.
4. The service worker for that proxy location then intercepts the request that was sent to the proxy location.

• We use Cloudflare Workers for the service worker
• The 'global-partytown.liquid' file routes to our custom built Shopify app, which serves as a Shopify App Proxy that routes to the service worker's location

5. The service worker then sends a postMessage to the proxy location’s main thread to get the real JavaScript value, synchronously blocking that service worker. The proxy location then sends the real value back to the service worker, unblocking it.

• The service worker's code houses the location to Partytown's assets library, which is where the real JavaScript value is fetched

6. With the value that was given to the service worker, the service worker sends that value back to the original web worker, which then unblocks the original web worker, allowing it to execute the rest of the code in the web worker.

• This allows heavy JavaScript tasks to be run asynchronously off the browser's main thread using a web worker while still forcing the web worker to run synchronously. The web worker needs to run synchronously by using a proxied service worker for the code to run correctly inside the web worker with valid JavaScript values that cannot be rendered due to its inability to access global objects, such as a simple task of a "document.querySelector()"

‍

Handling Shopify's Injected Scripts

Shopify uses Web Pixels to inject scripts inside a sandboxed environment in an iframe, preventing access to the top frame. This means Partytown cannot get manual/direct access to these scripts.

While there is a way to have Partytown pick up the scripts from the Web Pixel using sessionStorage, which will have to be implemented for each Web Pixel, it does not guarantee us access to every single script injected by Shopify.

Because of this, we use a mutation observer on the element to add a 'type="text/partytown"' attribute to each injected script, which can then be queried and placed inside of the web worker by Partytown.

• [(https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)]