Advanced React Iframe Monorepo

Welcome to the React Iframe monorepo! This project is a comprehensive toolkit for building advanced iframe-based applications in React, featuring powerful DOM manipulation, device emulation, and design mode capabilities.

👤 Credits

Created & Maintained by:

• Sean Filimon
• Etc.

📂 Project Structure

This monorepo is managed with Turbo and organized into applications and packages:

Apps

• apps/demo: A generic Vite + React application demonstrating how to consume the @react-iframe ecosystem. It showcases element selection, style injection, and device simulation.

Packages

• packages/react-iframe (@react-iframe/core):

  • The core component library.
  • Provides the <AdvancedIframe /> component.
  • Handles basic iframe rendering, ref forwarding, and event bridging.

• packages/dom (@react-iframe/dom):

  • Utilities for advanced DOM interaction.
  • State management for "Design Mode" features (selection, hovering, editing).
  • Tools for injecting styles and scripts dynamically.

• packages/devices (@react-iframe/devices):

  • Device definitions (iPhone, Pixel, Desktop, etc.).
  • Utilities for responsive frame sizing and scaling logic.

• packages/dom-parsers (@react-iframe/dom-parsers):

  • Parsers for analyzing and extracting structure from various framework projects.
  • Helps bridge the gap between source code and the rendered iframe DOM.

🚀 Features

• Declarative Iframe Rendering: Render iframes with React-friendly APIs.
• Deep DOM Selection: Select, highlight, and manipulate elements inside the iframe using standard CSS selectors.
• Design Mode: Built-in logic for selecting elements, handling hover states, and editing content visually.
• Device Emulation: Preview content across different device sizes and viewports.
• Style & Script Injection: Seamlessly inject custom CSS or JS into the iframe context.
• TypeScript Support: Fully typed for a robust development experience.

🛠 Getting Started

Prerequisites

• Node.js (v16+)
• pnpm (recommended) or npm

Installation

Install dependencies for the entire workspace:

pnpm install
# or
npm install

Running the Demo

Start the development environment:

pnpm dev
# or
npm run dev

This command uses Turbo to start the build/watch processes for dependent packages and launches the demo app (typically at http://localhost:5173).

Building

To build all packages and apps for production:

pnpm build

📖 Usage Example

Here is a simple example using the core package:

import React, { useRef } from 'react';
import { AdvancedIframe, AdvancedIframeHandle } from '@react-iframe/core';

const MyComponent = () => {
  const iframeRef = useRef<AdvancedIframeHandle>(null);

  const handleReady = (handle: AdvancedIframeHandle) => {
    // Select an element and change its color
    const title = handle.select<HTMLElement>('h1');
    if (title) {
      title.style.color = 'blue';
    }

    // Inject custom CSS
    handle.injectCSS('body { background-color: #f0f0f0; }');
  };

  return (
    <AdvancedIframe
      ref={iframeRef}
      initialContent="<h1>Hello World</h1>"
      onReady={handleReady}
    />
  );
};