Quick Start

Installation

npm install iframe-shield

Vanilla JavaScript

Create an instance, register your iframe, and everything else is automatic.

import { IframeShield } from 'iframe-shield';

const shield = new IframeShield({
  memoryBudgetMB: 500,
  quality: 'auto',
  maxConcurrentActive: 1,
});

const id = shield.register('#game-iframe', {
  estimatedMemoryMB: 700,
  priority: 1,
});

The iframe will now be managed automatically:

React

import { useIframeShield } from 'iframe-shield/react';

function GamePlayer({ gameUrl }) {
  const { iframeRef, stats, setQuality, freeze, resume } = useIframeShield({
    src: gameUrl,
    enabled: !!gameUrl,
    estimatedMemoryMB: 700,
    config: {
      deviceProfile: 'auto',
      quality: 'auto',
      crashRecovery: { enabled: true },
      debugger: {
        enabled: process.env.NODE_ENV === 'development',
        position: 'bottom-right',
        shortcut: 'ctrl+shift+q',
      },
    },
  });

  return <iframe ref={iframeRef} src={gameUrl} />;
}
Tip: The useIframeShield hook shares a single IframeShield instance across all components. No need to manage singletons.

Manual Controls

Override auto-pilot when needed:

// Change quality
shield.setQuality(id, 'low');

// Freeze iframe (level 1-3)
shield.freeze(id, 1);  // Light freeze, state preserved
shield.freeze(id, 3);  // Full freeze, memory released

// Resume from any level
shield.resume(id);

// Get current state
const stats = shield.getStats();
console.log(stats.memoryZone);  // 'green' | 'yellow' | 'red' | 'critical' | 'emergency'

// Cleanup
shield.dispose();

Next Steps