Real-time Preview

The Real-time Preview system is the core feedback engine of Onlook, providing instant visual updates and interactive testing capabilities through sophisticated CodeSandbox integration. It creates a seamless development experience where code changes are immediately reflected in a live, fully-functional web application environment, enabling rapid iteration and immediate validation of development work.

Product Specifications

User Experience Flow

The real-time preview creates an immersive development experience where users work directly with a live, fully-functional version of their web application. Every change is instantly reflected, creating a tight feedback loop that enables rapid iteration and confident development decisions.

Functional Requirements

Feature	End-to-End Business Logic and Rules
CodeSandbox Integration & Environment Management	User Intent: To work with a professional-grade development environment that provides all the capabilities of a modern web development setup without any local configuration. End-to-End Flow: 1. System - Sandbox Provisioning: When a project is opened, the system creates or connects to a CodeSandbox instance specifically for that project. This sandbox is a fully-featured development environment running in the cloud, complete with Node.js, package management, and build tools. 2. Backend - Project Synchronization: The system establishes a bidirectional sync between the local project state and the CodeSandbox environment. All project files, dependencies, and configurations are mirrored in real-time to ensure the sandbox always reflects the current project state. 3. System - Development Server Startup: The CodeSandbox environment automatically starts the appropriate development server (typically Next.js dev server) which handles hot-reloading, asset serving, and all development-time features that developers expect. 4. Frontend - Preview Integration: The live preview in Onlook’s interface displays the running application from the CodeSandbox environment through an embedded iframe, providing users with a window into their fully-functional application. Key Rules & Constraints: - Each project maintains its own isolated CodeSandbox environment to prevent conflicts. - The sandbox environment must support all standard Next.js and React development features. - File synchronization must be bidirectional and near-instantaneous to maintain development flow.
Hot-Reload and Instant Updates	User Intent: To see code changes reflected immediately in the running application without losing application state or experiencing disruptive page refreshes. End-to-End Flow: 1. System - File Change Detection: When any code modification occurs (through AI generation, visual editing, or direct code changes), the system immediately writes the changes to the appropriate files in the CodeSandbox environment. 2. CodeSandbox - Hot Module Replacement: The CodeSandbox development server detects the file changes and triggers its hot-reload system. This system intelligently determines which parts of the application need to be updated without affecting the rest. 3. System - Selective Component Updates: Instead of refreshing the entire page, the hot-reload system updates only the specific React components that were modified, preserving application state, user inputs, and current navigation context. 4. Frontend - Seamless Visual Updates: Users see their changes appear instantly in the preview without any loading indicators, page flashes, or loss of context, creating a seamless editing experience that feels like direct manipulation. Key Rules & Constraints: - Updates must preserve application state whenever possible to maintain editing context. - The system must handle both individual file changes and batch updates efficiently. - Hot-reload must work reliably across different types of changes (components, styles, configuration).
Interactive Application Testing	User Intent: To test and validate the full functionality of the web application directly within the development environment, including user interactions, form submissions, and dynamic behaviors. End-to-End Flow: 1. System - Full Application Functionality: The preview environment runs the complete, unmodified application with all its interactive features enabled. Users can click buttons, fill forms, navigate between pages, and interact with all UI elements exactly as end-users would. 2. Frontend - Seamless Interaction Mode: Users can switch between “editing mode” (where clicks select elements for modification) and “interaction mode” (where clicks trigger normal application behavior) through simple interface controls. 3. System - State Preservation During Edits: When users make changes to the application while testing, the system intelligently preserves relevant application state so that testing can continue without losing progress or context. 4. Frontend - Real-time Validation: Users can immediately validate that their changes work correctly by interacting with the modified elements, creating a tight feedback loop between development and testing. Key Rules & Constraints: - The preview must support all standard web application features including JavaScript events, API calls, and routing. - Mode switching between editing and interaction must be intuitive and clearly indicated. - Application state should be preserved across reasonable editing operations to maintain testing context.
Multi-Device Preview System	User Intent: To test and validate how the application appears and behaves across different screen sizes and device types without leaving the development environment. End-to-End Flow: 1. System - Device Configuration Management: The system maintains a comprehensive library of device presets including popular smartphones, tablets, laptops, and desktop configurations, each with accurate screen dimensions, pixel densities, and viewport characteristics. 2. Frontend - Dynamic Viewport Adjustment: When users select a device preset, the preview container dynamically adjusts its dimensions, pixel density simulation, and viewport characteristics to accurately represent the selected device. 3. System - Responsive Design Testing: The application’s responsive design features (CSS media queries, flexible layouts) automatically activate based on the simulated viewport, allowing users to see exactly how their design adapts to different screen sizes. 4. Frontend - Interactive Device Switching: Users can rapidly switch between different device presets to test responsive breakpoints, compare layouts across devices, and ensure consistent user experience across all target platforms. Key Rules & Constraints: - Device simulations must accurately reflect real-world viewport dimensions and characteristics. - Switching between devices should be instant and preserve the current application state. - The system must support both portrait and landscape orientations for mobile devices.
Visual Element Selection and Highlighting	User Intent: To precisely identify and select specific elements within the running application for editing or modification through direct visual interaction. End-to-End Flow: 1. System - Element Identification Infrastructure: Every interactive element in the application is automatically augmented with unique identifiers that create a precise mapping between visual elements and their corresponding code representations. 2. Frontend - Interactive Selection Interface: When users hover over elements in the preview, the system provides visual feedback through highlighting, borders, or overlays that clearly indicate which element would be selected upon clicking. 3. System - Precise Element Mapping: When an element is clicked, the system captures not only the element’s unique identifier but also its context within the component hierarchy, its current properties, and its relationship to other elements. 4. Frontend - Selection Confirmation and Context: Selected elements receive persistent visual indicators, and the interface updates to show relevant editing options, property panels, or contextual tools specific to the selected element type. Key Rules & Constraints: - Element selection must be pixel-accurate and work reliably across all supported browsers. - The selection system must handle complex scenarios like overlapping elements, nested components, and dynamic content. - Visual feedback must be clear and non-intrusive, not interfering with the application’s normal appearance.
Cross-Frame Communication Bridge	User Intent: To enable seamless data exchange and command execution between the main editor interface and the running application preview without security vulnerabilities or performance issues. End-to-End Flow: 1. System - Secure Communication Channel: The system establishes a secure, bidirectional communication channel between the main editor application and the preview iframe using the Penpal library, which provides type-safe, asynchronous messaging capabilities. 2. Backend - Script Integration: During the application build process, the system automatically injects a communication bridge script into the application that enables it to receive commands from the editor and send information back. 3. System - Command and Event Handling: The communication bridge supports a comprehensive set of commands (highlight elements, update properties, inject code) and events (element selection, user interactions, application state changes) that enable rich integration between editor and preview. 4. Frontend - Transparent Operation: The communication system operates transparently to users, enabling features like real-time editing, element selection, and property synchronization without any visible complexity or performance impact. Key Rules & Constraints: - All communication must be secure and prevent unauthorized access to editor or application data. - The communication bridge must not interfere with normal application functionality or performance. - Message passing must be reliable and handle network interruptions gracefully.

Technical Solution

Natural Language Technical Solution

The Real-time Preview system operates through a sophisticated integration with CodeSandbox, a cloud-based development environment that provides full Next.js development capabilities. When a project is opened, the system establishes a dedicated CodeSandbox instance that serves as the live development environment.

The Sandbox Manager maintains bidirectional synchronization between the local project state and the remote CodeSandbox environment. Every file change, whether from AI generation, visual editing, or direct code modification, is immediately propagated to the sandbox through a robust file synchronization system.

The CodeSandbox environment runs a complete Next.js development server with hot-module replacement capabilities. This means that when files change, only the affected components are updated without losing application state or requiring full page reloads.

The preview is displayed in the main editor through an embedded iframe that loads the running application from the CodeSandbox environment. A communication bridge using the Penpal library enables secure, bidirectional messaging between the editor and the preview, allowing for features like element selection, property synchronization, and interactive mode switching.

The system also provides multi-device simulation by dynamically adjusting the iframe dimensions and viewport characteristics to match selected device presets, enabling comprehensive responsive design testing without leaving the development environment.

End-to-end Execution Sequence Diagram

AI Replication & Reference