Ajeet Singh

Posted on Jan 26

Off-Main-Thread Architecture: Let the Main Thread Breathe

#webdev #javascript #performance #architecture

Modern web applications demand more from browsers than ever before. Analytics, personalization, A/B testing, chat widgets, and countless third-party scripts compete for the same precious resource: the main thread. When this thread gets overwhelmed, users experience jank, delayed interactions, and frustration.

Off-Main-Thread (OMT) Architecture is a design pattern that moves non-UI work away from the main thread, allowing the browser to stay responsive while still executing heavy JavaScript operations.

Understanding the Main Thread Problem
Web Workers: The Foundation
How Off-Main-Thread Architecture Works
Partytown: OMT Made Practical
Advantages of OMT Architecture
Complexities and Challenges
Production Usage
Things to Keep in Mind
Further Reading

Understanding the Main Thread Problem

The browser's main thread is responsible for:

Parsing HTML and CSS
Executing JavaScript
Calculating layouts and styles
Painting pixels to the screen
Handling user interactions (clicks, scrolls, typing)

When you add heavy JavaScript execution to this list, something has to wait. That "something" is usually user interaction—causing the dreaded jank.

┌──────────────────────────────────────────────────────────────────────┐
│                        MAIN THREAD TIMELINE                          │
├──────────────────────────────────────────────────────────────────────┤
│  Parse   │   JS    │  Layout │  Paint  │   JS    │  Layout │  Paint │
│  HTML    │ Execute │  Calc   │  Screen │ Execute │  Calc   │  Screen│
├──────────────────────────────────────────────────────────────────────┤
│          │         │         │         │         │         │        │
│          │  ████████████████████████████████████  │         │        │
│          │     Long Task (>50ms) - UI Blocked!   │         │        │
│          │  User clicks here... waits... waits..│         │        │
└──────────────────────────────────────────────────────────────────────┘

The 50ms Rule

According to the RAIL performance model, any task taking longer than 50 milliseconds is considered a "long task" and risks making the UI feel sluggish. Third-party scripts like Google Analytics, Facebook Pixel, or chat widgets can easily exceed this threshold.

Web Workers: The Foundation

Web Workers are the browser's mechanism for running JavaScript in background threads, separate from the main thread.

Types of Workers

Worker Type	Purpose	DOM Access	Scope
Dedicated Worker	General computation	❌ None	Single page
Shared Worker	Shared state across tabs	❌ None	Multiple pages (same origin)
Service Worker	Network proxy, offline	❌ None	Origin-wide

Basic Web Worker Example

main.js (Main Thread)

// Create a new worker
const worker = new Worker('worker.js');

// Send data to the worker
worker.postMessage({ numbers: [1, 2, 3, 4, 5], operation: 'sum' });

// Receive results from the worker
worker.onmessage = (event) => {
  console.log('Result:', event.data); // Result: 15
};

// Handle errors
worker.onerror = (error) => {
  console.error('Worker error:', error.message);
};

worker.js (Worker Thread)

self.onmessage = (event) => {
  const { numbers, operation } = event.data;

  let result;
  if (operation === 'sum') {
    result = numbers.reduce((a, b) => a + b, 0);
  }

  // Send result back to main thread
  self.postMessage(result);
};

Key Limitations of Web Workers

No DOM Access: Workers cannot directly read or modify the DOM
No window Object: Limited browser APIs available
Communication Overhead: Data must be serialized via postMessage()
Separate Context: No shared memory (unless using SharedArrayBuffer)

How Off-Main-Thread Architecture Works

OMT architecture uses workers strategically to keep heavy operations away from the main thread while still allowing those operations to interact with the DOM when necessary.

The Communication Pattern

┌─────────────────────────────────────────────────────────────────────────────┐
│                         OFF-MAIN-THREAD ARCHITECTURE                         │
└─────────────────────────────────────────────────────────────────────────────┘

    MAIN THREAD                                      WORKER THREAD
┌─────────────────────┐                        ┌─────────────────────┐
│                     │                        │                     │
│  ┌───────────────┐  │     postMessage()      │  ┌───────────────┐  │
│  │     DOM       │  │  ◄──────────────────── │  │  Heavy JS     │  │
│  │   Rendering   │  │                        │  │  Execution    │  │
│  │   Layout      │  │  ────────────────────► │  │  (Analytics,  │  │
│  │   Paint       │  │     postMessage()      │  │   Parsing,    │  │
│  └───────────────┘  │                        │  │   Compute)    │  │
│                     │                        │  └───────────────┘  │
│  ┌───────────────┐  │                        │                     │
│  │ User Input    │  │   Proxy Layer for      │  ┌───────────────┐  │
│  │ Event Loop    │  │   DOM Operations       │  │  Virtual DOM  │  │
│  │ (clicks,      │  │  ◄──────────────────── │  │  Proxy        │  │
│  │  scroll,      │  │  ────────────────────► │  │  Interface    │  │
│  │  typing)      │  │   Results/Data         │  └───────────────┘  │
│  └───────────────┘  │                        │                     │
│                     │                        │                     │
│  🟢 Stays Fast!     │                        │  🔄 Does Heavy Work │
└─────────────────────┘                        └─────────────────────┘

The Flow

Initialize: Main thread creates a worker and loads heavy scripts into it
Proxy Setup: A proxy layer intercepts DOM API calls in the worker
Message Passing: DOM operations become serialized messages
Main Thread Execution: Only actual DOM mutations run on main thread
Response: Results are sent back to the worker
UI Remains Responsive: Main thread is free for rendering and input

Partytown: OMT Made Practical

Partytown by Builder.io is a library that makes off-main-thread architecture accessible. It runs third-party scripts inside a web worker while proxying DOM access.

How Partytown Works

┌───────────────────────────────────────────────────────────────────────────┐
│                          PARTYTOWN ARCHITECTURE                           │
└───────────────────────────────────────────────────────────────────────────┘

┌─────────────────────┐                        ┌─────────────────────────────┐
│    MAIN THREAD      │                        │      WEB WORKER             │
│                     │                        │                             │
│  1. Load Partytown  │                        │  2. Scripts loaded here     │
│     runtime         │ ─────────────────────► │     (GA, GTM, FB Pixel)     │
│                     │                        │                             │
│  ┌───────────────┐  │                        │  ┌───────────────────────┐  │
│  │ Real DOM      │  │  3. Proxy calls        │  │ Virtual DOM Proxy     │  │
│  │               │  │ ◄───────────────────── │  │                       │  │
│  │ document      │  │  "read document.cookie"│  │ document.cookie       │  │
│  │ window        │  │                        │  │ window.location       │  │
│  │ localStorage  │  │  4. Real values        │  │ localStorage          │  │
│  │               │  │ ─────────────────────► │  │                       │  │
│  └───────────────┘  │  "session_id=abc123"   │  └───────────────────────┘  │
│                     │                        │                             │
│  5. Only minimal    │                        │  Script thinks it has       │
│     DOM work here   │                        │  normal DOM access          │
└─────────────────────┘                        └─────────────────────────────┘

Basic Setup

1. Install Partytown

npm install @builder.io/partytown

2. Copy library files to your public folder

npx partytown copylib public/~partytown

3. Add to your HTML

<!DOCTYPE html>
<html>
<head>
  <!-- Partytown configuration (optional) -->
  <script>
    partytown = {
      forward: ['dataLayer.push'],  // Forward these calls to worker
      debug: true                    // Enable debug mode
    };
  </script>

  <!-- Load Partytown runtime -->
  <script src="/~partytown/partytown.js"></script>

  <!-- Third-party scripts with type="text/partytown" -->
  <script type="text/partytown" src="https://www.googletagmanager.com/gtag/js?id=GA_ID"></script>
  <script type="text/partytown">
    window.dataLayer = window.dataLayer || [];
    function gtag(){ dataLayer.push(arguments); }
    gtag('js', new Date());
    gtag('config', 'GA_ID');
  </script>
</head>
<body>
  <!-- Your app content -->
</body>
</html>

Framework Integration

Next.js

// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document';
import { Partytown } from '@builder.io/partytown/react';

export default function Document() {
  return (
    <Html>
      <Head>
        <Partytown forward={['dataLayer.push']} />
        <script
          type="text/partytown"
          src="https://www.googletagmanager.com/gtag/js?id=GA_ID"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

React (Vite/CRA)

// index.html or App component
import { Partytown } from '@builder.io/partytown/react';

function App() {
  return (
    <>
      <Partytown forward={['dataLayer.push', 'fbq']} />
      {/* Your app */}
    </>
  );
}

Under the Hood: The Proxy Magic

Partytown uses several clever techniques:

// Simplified view of how Partytown proxies work
// In the worker, Partytown creates proxy objects:

const documentProxy = new Proxy({}, {
  get(target, prop) {
    if (prop === 'cookie') {
      // Synchronously request from main thread
      return syncRequest('document.cookie');
    }
    // ... handle other properties
  },
  set(target, prop, value) {
    if (prop === 'cookie') {
      // Send to main thread
      postToMain({ type: 'set', path: 'document.cookie', value });
    }
    return true;
  }
});

// Scripts in the worker see this proxy as the real document

Synchronous Access Challenge

Web Workers are asynchronous by nature, but many third-party scripts expect synchronous DOM access. Partytown solves this using:

Atomics and SharedArrayBuffer (when available)
Synchronous XMLHttpRequest (fallback)
Service Worker intermediary (another fallback)

Advantages of OMT Architecture

1. Improved Core Web Vitals

Metric	Impact
First Input Delay (FID)	Reduced blocking = faster response to first interaction
Interaction to Next Paint (INP)	Less main thread contention = smoother interactions
Total Blocking Time (TBT)	Heavy scripts don't contribute to blocking time
Largest Contentful Paint (LCP)	Main thread free to render content faster

2. Better User Experience

BEFORE OMT:
User clicks → [Wait 200ms for JS] → Response
                    ↑
              Main thread busy
              with analytics

AFTER OMT:
User clicks → [5ms] → Response
                ↑
          Main thread free
          Analytics in worker

3. Isolation and Stability

Crash Isolation: A misbehaving script in a worker won't freeze the page
Memory Isolation: Worker memory issues don't affect main thread
CPU Isolation: Worker can use dedicated CPU time

4. Clearer Performance Budgets

// You can now categorize scripts
const mainThreadScripts = [
  'app-bundle.js',      // Core app logic
  'critical-ui.js',     // UI interactions
];

const workerScripts = [
  'analytics.js',       // Google Analytics
  'tracking.js',        // Marketing pixels  
  'chat-widget.js',     // Customer support
  'personalization.js', // A/B testing
];

5. Measurable Improvements

Real-world results from Partytown users:

Up to 99% reduction in third-party script main thread time
10-50ms reduction in Total Blocking Time
Significant FID improvements on script-heavy marketing pages

Complexities and Challenges

1. Communication Overhead

┌─────────────────────────────────────────────────────────────────┐
│                    MESSAGE PASSING OVERHEAD                      │
└─────────────────────────────────────────────────────────────────┘

Without OMT:
document.cookie (1 operation) → 0.01ms

With OMT:
document.cookie (1 operation):
  Worker: Serialize request         →  0.1ms
  Worker → Main: postMessage        →  0.5ms
  Main: Execute                     →  0.01ms
  Main → Worker: postMessage        →  0.5ms
  Worker: Deserialize response      →  0.1ms
                              Total:   ~1.2ms

For chatty scripts with many DOM calls, this adds up!

2. Synchronous API Challenges

Many browser APIs are synchronous but workers are async:

// This works in main thread:
const width = element.offsetWidth;  // Immediate value

// In a worker, this needs special handling:
const width = await getFromMainThread('element.offsetWidth');
// Or Partytown's sync mechanism via Atomics

3. Limited Browser API Access

Workers don't have access to:

DOM (document, Element, etc.)
window (partially available as self)
localStorage / sessionStorage (directly)
Certain APIs like alert(), confirm(), prompt()

4. Debugging Complexity

┌─────────────────────────────────────────────────────────────────┐
│                    DEBUGGING CHALLENGES                          │
└─────────────────────────────────────────────────────────────────┘

Traditional:
Console → Script → Error → Stack trace → Line number

With OMT:
Console → Worker proxy → Actual script → Error → 
  ↓
Proxied stack trace → Virtual line number → 🤔 Where?

DevTools improvements needed:

Trace across thread boundaries
Map proxied calls to original scripts
Monitor message passing performance

5. Script Compatibility

Not all scripts work well in workers:

Script Type	OMT Compatibility
Analytics (GA, GTM)	✅ Excellent
Chat widgets	⚠️ May need config
A/B testing	✅ Usually good
Payment SDKs	❌ Often problematic
UI libraries	❌ Not suitable
Heavy DOM manipulation	❌ Not suitable

6. State Synchronization

// Challenge: Keeping state in sync
// Main thread state:
window.userLoggedIn = true;

// Worker sees stale state:
if (window.userLoggedIn) {  // Might be outdated!
  trackLoggedInUser();
}

// Solution: Forward state changes
partytown = {
  forward: ['dataLayer.push', 'updateUserState']
};

Production Usage

Companies Using OMT Architecture

Company	Use Case
Builder.io	Creator of Partytown, uses it extensively
Shopify	Hydrogen framework supports Partytown
Netlify	Edge functions + Partytown for marketing sites
Various e-commerce	Marketing-heavy sites with many third-party scripts

Real Production Examples

E-commerce Site

Before Partytown:
- Total Blocking Time: 850ms
- Third-party script time: 600ms
- FID: 180ms

After Partytown:
- Total Blocking Time: 280ms  (-67%)
- Third-party script time: ~0ms on main thread
- FID: 45ms (-75%)

Marketing Landing Page

Scripts moved to worker:
- Google Analytics
- Google Tag Manager
- Facebook Pixel
- Hotjar
- Intercom

Result:
- TTI improved by 40%
- Conversion rate increased 12%

Browser Support

Browser	Support
Chrome 80+	✅ Full support
Firefox 79+	✅ Full support
Safari 15+	✅ Full support
Edge 80+	✅ Full support
IE 11	❌ No worker support

Things to Keep in Mind

1. Start with the Right Candidates

✅ GOOD CANDIDATES:
├── Analytics scripts (GA, Adobe Analytics)
├── Tag managers (GTM, Tealium)
├── Marketing pixels (Facebook, LinkedIn, Twitter)
├── Heatmap tools (Hotjar, FullStory)
├── Chat widgets (Intercom, Drift)
└── A/B testing (Optimizely, VWO)

❌ POOR CANDIDATES:
├── Payment processors (Stripe.js, PayPal)
├── Authentication SDKs
├── Core UI libraries
├── Real-time collaboration tools
└── Anything requiring immediate DOM feedback

2. Measure Before and After

// Set up performance monitoring
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.duration > 50) {
      console.log('Long Task:', entry.duration, 'ms');
      // Send to analytics
    }
  }
});
observer.observe({ entryTypes: ['longtask'] });

// Track Core Web Vitals
import { onFID, onINP, onTBT } from 'web-vitals';

onFID(console.log);
onINP(console.log);

3. Implement Gradually

Phase 1: Single Script
├── Move Google Analytics to Partytown
├── Monitor for 1-2 weeks
├── Check: Events still tracking?
└── Check: Performance improved?

Phase 2: Expand
├── Add GTM
├── Add marketing pixels
├── Monitor each addition
└── Document any shims needed

Phase 3: Optimize
├── Fine-tune forwarding config
├── Add error monitoring for workers
└── Create runbook for issues

4. Handle Errors Properly

// Configure error handling
partytown = {
  forward: ['dataLayer.push'],

  // Catch errors from worker
  mainWindowAccessors: ['onerror'],

  // Log worker errors
  resolveUrl: (url) => {
    console.log('Partytown loading:', url);
    return url;
  }
};

// Add global error handler for worker issues
window.addEventListener('error', (event) => {
  if (event.filename?.includes('partytown')) {
    // Log to your error tracking service
    trackError('Partytown Error', event.message);
  }
});

5. Have a Rollback Plan

<!-- Feature flag approach -->
<script>
  const usePartytown = window.FEATURE_FLAGS?.partytown ?? true;

  if (usePartytown) {
    // Load Partytown version
    document.write('<script src="/~partytown/partytown.js"><\/script>');
  }
</script>

<!-- Scripts that can fallback -->
<script 
  type="text/partytown"
  data-fallback-type="text/javascript"
  src="https://analytics.example.com/script.js"
></script>

6. Test Third-Party Script Functionality

// Create a test suite for moved scripts
describe('Analytics in Partytown', () => {
  it('should track page views', async () => {
    // Trigger page view
    gtag('event', 'page_view');

    // Verify it was received (check your analytics dashboard or mock)
    await waitFor(() => {
      expect(analyticsReceived('page_view')).toBe(true);
    });
  });

  it('should track custom events', async () => {
    gtag('event', 'button_click', { button_id: 'cta' });

    await waitFor(() => {
      expect(analyticsReceived('button_click')).toBe(true);
    });
  });
});

Alternative Approaches

While Partytown is popular, other OMT solutions exist:

1. Manual Web Workers

// For computation-heavy tasks
const computeWorker = new Worker('compute.js');

// Offload data processing
computeWorker.postMessage({ 
  action: 'processLargeDataset',
  data: massiveArray 
});

2. Comlink (by Google)

// Simplifies worker communication
import * as Comlink from 'comlink';

// worker.js
const api = {
  async processData(data) {
    return heavyComputation(data);
  }
};
Comlink.expose(api);

// main.js
const worker = new Worker('worker.js');
const api = Comlink.wrap(worker);
const result = await api.processData(largeData);

3. Workerize

// Automatically moves functions to workers
import workerize from 'workerize';

const worker = workerize(`
  export function expensiveCalculation(n) {
    // Heavy computation
    return result;
  }
`);

const result = await worker.expensiveCalculation(1000000);

Conclusion

Off-Main-Thread Architecture represents a fundamental shift in how we think about web performance. Instead of fighting for main thread time, we acknowledge it as a scarce resource and protect it for what matters most: rendering and responding to users.

Key Takeaways:

The main thread is precious - Reserve it for UI work
Web Workers are mature - Excellent browser support
Partytown makes OMT practical - No need to rewrite scripts
Measure everything - Use Core Web Vitals as your guide
Start small - Move one script, validate, expand
Have a rollback plan - Things can go wrong

The web is getting heavier, but our users' patience isn't increasing. Off-main-thread architecture gives us a way to have our analytics cake and eat our performance too.

Table of Contents