threadpeace

v0.1.1

Published

9 days ago

Move third-party scripts and heavy computations off the main thread with minimal code changes

0High
0Medium
0Low

typeofnull

web-worker performance third-party-scripts tbt main-thread

Why threadpeace?

Third-party analytics scripts (GTM, GA, Amplitude, Pixel) and CPU-heavy frontend logic both compete for the main thread — causing jank, high Total Blocking Time, and poor Core Web Vitals. threadpeace solves both:

Script offloading — change type on a <script> tag, the rest is automatic
Function offloading — wrap a function with offload(), call it exactly the same way
Task events — real-time progress, completion, and error events
Worker pool — automatic pooling with configurable concurrency and strategies
Debug overlay — live in-browser panel for worker/task monitoring

npm install threadpeace

Quick start

Script offloading — one attribute change

<!-- Before -->
<script src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>

<!-- After -->
<script type="threadpeace" src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"></script>

Add the bootstrap snippet to <head> before your scripts:

import { injectSnippet } from 'threadpeace/snippet';
injectSnippet({ forward: ['dataLayer', 'gtag', 'fbq'] });

Function offloading

import { init, offload } from 'threadpeace';

init({ pool: { min: 1, max: 4 } });

const processRows = offload((rows: number[]): number => {
  return rows.reduce((acc, n) => acc + n * n, 0);
});

const result = await processRows(myLargeArray); // runs in a worker

Task with progress + cancellation

import { task } from 'threadpeace';

const handle = task(
  (count: number) => {
    for (let i = 0; i < count; i++) {
      heavyWork(i);
      report(i / count); // built-in — no import needed
    }
    return { total: count };
  },
  [10_000],
);

handle
  .on('progress', (pct) => progressBar.set(pct))
  .on('complete', (result) => showDashboard(result))
  .on('error', (err) => handleError(err));

handle.cancel(); // safe to call at any time

// Or just await:
const result = await handle;

How it compares

| Feature | 🧵 threadpeace | Partytown | Comlink | workerize | workerpool | |---|:---:|:---:|:---:|:---:|:---:| | Script offloading (third-party) | ✅ | ✅ | — | — | — | | Function offloading | ✅ | — | ✅ | ✅ | ✅ | | Worker pool (min/max/strategies) | ✅ | — | — | — | ✅ | | Progress events | ✅ | — | — | — | ✅ | | Cancellation | ✅ | — | — | — | ✅ | | Module proxy | ✅ | — | ✅ | — | ✅ | | DOM proxy (window/document) | ✅ | ✅ | — | — | — | | Debug overlay | ✅ | — | — | — | — | | TypeScript-first | ✅ | partial | ✅ | ✅ | ✅ | | Zero runtime dependencies | ✅ | — | ✅ | ✅ | — | | Bundle size (gzipped) | ~15 KB | ~17 KB | ~2 KB | ~1 KB | ~14 KB |

Partytown solves script offloading only. Comlink is a lightweight RPC bridge with no pool or events. workerize requires Webpack and has no pool. workerpool is Node.js-first with no script offloading or debug tooling.

Third-party script compatibility

| Script | Status | Notes | |---|---|---| | Google Tag Manager | ✅ Works | Add dataLayer to forward[] | | Google Analytics (GA4) | ✅ Works | — | | Amplitude | ✅ Works | — | | TikTok Pixel | ✅ Works | — | | Twitter/X Pixel | ✅ Works | — | | Chartbeat | ✅ Works | Enable noCookies mode | | Facebook Pixel | ⚠️ Needs proxy | Requires a CORS reverse proxy — see docs | | Sovrn / Ad-tech | 🧪 Experimental | Start with loadOnMainThread: [/sovrn/] |

Next.js

npm install threadpeace

// next.config.js
const { withThreadPeace } = require('threadpeace/next');
module.exports = withThreadPeace({}, { forward: ['dataLayer', 'gtag', 'fbq'] });

// app/layout.tsx
import { ThreadPeaceScript } from 'threadpeace/next';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <ThreadPeaceScript forward={['dataLayer', 'gtag', 'fbq']} />
        <script type="threadpeace" src="https://www.googletagmanager.com/gtag/js?id=G-XXXX" />
      </head>
      <body>{children}</body>
    </html>
  );
}

Package exports

| Import | Contents | |---|---| | threadpeace | init, offload, task, module, debugBus, getPoolStats, mountDebugOverlay | | threadpeace/next | withThreadPeace, ThreadPeaceScript, useThreadPeace | | threadpeace/snippet | getSnippet, injectSnippet |

Documentation

Full docs at threadpeace.amanagarwal.xyz

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme