codeYaan Logo Blog
Home Blog Services Courses
Login
Partytown: Offload Third-Party Scripts to Web Workers
AI TOOLS March 11, 2026, 5:30 a.m.

Partytown: Offload Third-Party Scripts to Web Workers

When you load a modern website, a silent performance thief often lurks in the background: third‑party scripts. These snippets—analytics, ads, social widgets—run on the main thread, blocking rendering and inflating your TTI. Partytown, an open‑source library from Builder.io, offers a clever workaround by moving those heavy scripts into Web Workers. The result? Faster, smoother pages without sacrificing the functionality you rely on.

Why Third‑Party Scripts Hurt Performance

Every script you add to <head> competes for the browser’s single JavaScript main thread. When a third‑party script performs network I/O, parses large bundles, or executes heavy DOM queries, the main thread stalls. Users experience jank, delayed interactivity, and higher bounce rates.

Traditional mitigation strategies—async/defer, lazy‑loading, or CDN caching—help, but they don’t eliminate the fundamental problem: the script still executes on the main thread. That’s where Partytown shines, because Web Workers run in a separate thread with their own event loop, isolated from the UI thread.

What is Partytown?

Partytown is a lightweight runtime that intercepts calls to known third‑party APIs (like window.ga, window.fbq, etc.) and forwards them to a dedicated Web Worker. The worker loads the original script, executes it, and proxies any results back to the main thread. From the page’s perspective, nothing changes—only the execution context moves.

The library ships with a small partytown.js shim and a ~partytown folder containing the worker bundle. Once the shim is loaded, you can tell Partytown which scripts to offload via a simple HTML attribute or a JSON config.

Getting Started

Step 1: Install the package

Partytown can be added via npm, Yarn, or a CDN. For most projects, npm is the cleanest approach:

npm install @builder.io/partytown --save-dev

After installation, copy the static assets to your public folder. Many build tools provide a helper script:

npx partytown copy

This command creates a ~partytown directory containing partytown.js, partytown.js.map, and the worker bundle.

Step 2: Add the shim to your HTML

Place the shim as early as possible, preferably right after the opening <head> tag. The shim registers the worker and rewrites script URLs that carry the type="text/partytown" attribute.

<head>
  <script src="/~partytown/partytown.js"></script>
  ...
</head>

Step 3: Offload a third‑party script

Convert any third‑party script tag to use type="text/partytown". For example, to move Google Analytics (gtag.js) off the main thread:

<script type="text/partytown" src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script type="text/partytown">
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
</script>

From here on, all GA calls are executed inside the worker, freeing the main thread for layout, paint, and user interaction.

Advanced Configuration

Customizing the Forwarded APIs

Partytown ships with a default whitelist of known APIs. If you need to offload a script that uses a custom global object, add it to the partytown-config.js file:

// partytown-config.js
self.partytown = {
  forward: ['myCustomAnalytics', 'myCustomAnalytics.track']
};

Place this file alongside partytown.js and reference it in the shim:

<script src="/~partytown/partytown.js" data-config="/~partytown/partytown-config.js"></script>

Handling DOM‑Dependent Scripts

Some third‑party widgets query the DOM during initialization (e.g., document.querySelector). Because workers lack direct DOM access, Partytown proxies a minimal subset of DOM APIs. If a script fails, you can enable the debug flag to see detailed logs.

// partytown-config.js
self.partytown = {
  debug: true,
  resolveUrl: (url) => url.replace('cdn.example.com', 'cdn-mirror.example.com')
};

The resolveUrl hook is handy for rewriting URLs on the fly—perfect for CDNs, regional mirrors, or A/B testing.

Real‑World Use Cases

  • E‑commerce tracking: Offload Google Tag Manager and Facebook Pixel to keep checkout pages buttery smooth.
  • Content publishing: Move Disqus or Commento comment widgets into a worker, preventing them from blocking article rendering.
  • Ad tech: Run header bidding scripts in a worker to isolate latency spikes from user‑visible content.

Let’s walk through a concrete scenario: an online store that uses both GTM and a chat widget. The chat widget injects a heavy script that frequently polls the server, causing noticeable jank on mobile devices. By wrapping both scripts with type="text/partytown", the store saw a 45 % reduction in FCP and a 30 % boost in TTI on a mid‑range Android phone.

Performance Benchmarks

Below is a simplified benchmark table gathered from Lighthouse runs on a sample page before and after Partytown integration:

  1. Baseline (no Partytown)
    • FCP: 2.4 s
    • TTI: 5.8 s
    • Main‑thread busy time: 3.2 s
  2. After Partytown (GA + FB Pixel offloaded)
    • FCP: 1.9 s (≈ 20 % faster)
    • TTI: 3.7 s (≈ 36 % faster)
    • Main‑thread busy time: 1.1 s

Note that the worker itself consumes CPU, but because it runs on a separate thread, the UI thread remains responsive. The net gain is especially pronounced on devices with limited cores.

Pro Tips

Tip 1 – Scope wisely. Only offload scripts that truly block the main thread. Tiny utilities (e.g., a simple polyfill) add unnecessary overhead if moved to a worker.

Tip 2 – Pre‑warm the worker. Load partytown.js early and use preload for heavy third‑party bundles. This reduces the “cold start” latency when the worker first executes the script.

Tip 3 – Monitor with the debug console. Enable self.partytown.debug = true in development. The console will emit messages like “Forwarding window.fbq to worker” and highlight any unsupported APIs.

Putting It All Together – A Full Example

Below is a minimal yet complete HTML page that demonstrates Partytown with Google Analytics, a custom analytics object, and a chat widget. The example includes the configuration file, the shim, and three script tags.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Partytown Demo</title>

  <!-- Load Partytown shim first -->
  <script src="/~partytown/partytown.js"
          data-config="/~partytown/partytown-config.js"></script>

  <!-- Offload Google Analytics -->
  <script type="text/partytown"
          src="https://www.googletagmanager.com/gtag/js?id=G-DEM0"></script>
  <script type="text/partytown">
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'G-DEM0');
  </script>

  <!-- Offload a custom analytics library -->
  <script type="text/partytown" src="/js/custom-analytics.js"></script>
  <script type="text/partytown">
    myCustomAnalytics.track('page_view', {path: location.pathname});
  </script>

  <!-- Offload a chat widget that polls the server every 5 s -->
  <script type="text/partytown"
          src="https://cdn.chatprovider.com/widget.js"></script>
  <script type="text/partytown">
    ChatWidget.init({userId: '12345'});
  </script>
</head>
<body>
  <h1>Welcome to the Partytown Demo</h1>
  <p>Open your browser’s devtools and watch the main thread stay idle while the third‑party scripts run in the background.</p>
</body>
</html>

Notice how each third‑party script uses the same type="text/partytown" attribute. The configuration file (partytown-config.js) could look like this:

// partytown-config.js
self.partytown = {
  debug: false,
  forward: ['myCustomAnalytics', 'myCustomAnalytics.track'],
  resolveUrl: (url) => url.replace('cdn.chatprovider.com', 'cdn-eu.chatprovider.com')
};

Deploy the page, run a Lighthouse audit, and you’ll see the main thread idle time drop dramatically. The same pattern scales to larger applications—just remember to keep the list of forwarded APIs tidy.

Conclusion

Partytown offers a pragmatic, standards‑based solution to one of the web’s most stubborn performance problems: third‑party script bloat. By delegating heavy scripts to a Web Worker, you preserve the functional benefits of analytics, ads, and widgets while delivering a snappier user experience. The library is easy to integrate, highly configurable, and backed by real‑world performance gains. As browsers continue to evolve, leveraging workers for non‑UI work will become a best practice—Partytown puts that practice within reach today.

Share this article
Back to Blog