Documentation

Responsivelyonline is a browser-based multi-viewport website previewer. No installation or account is required for the web version.

Quick Start

1. Open the workspace at /workspace
2. Type or paste a URL in the address bar — for example example.com or https://stripe.com
3. Press Preview or hit Enter — four device viewports load immediately
4. Pan the canvas by clicking and dragging the background; zoom with the scroll wheel

Self-Hosting Locally

Requires Node.js 18.18 or newer.

git clone https://github.com/responsively-org/responsively-app
npm install
npm run dev    # → http://localhost:3000

In development mode, localhost and private network addresses (e.g. 192.168.x.x) are accessible. To allow them in a production build, set ALLOW_PRIVATE_HOSTS=true.

URL Normalization

• example.com → https://example.com (https:// added automatically)
• localhost:3000 → http://localhost:3000 (http:// for local)
• Malformed URLs and non-HTTP/HTTPS schemes are rejected with a clear error message

Each device preview is a native <iframe> sized to its configured CSS pixel dimensions. A transform: scale() wrapper makes it smaller on screen — so the site's media queries always see the true device viewport size.

Default Device Presets

Per-Device Controls

• Device name ▾ — Switch this preview to another preset or custom size
• Rotate — Swap width and height without reloading (animated transition)
• Reload — Reload only this preview
• 50 / 75 / 100 / Fit — Zoom this device; Fit uses a shared proportional scale
• Full Screen — Uses the browser Fullscreen API on this device preview
• Open in New Tab — Opens the target URL directly
• Screenshot — Captures via Screen Capture API (browser permission required)
• ✕ — Remove this device from the workspace

Custom Viewports

Click Add Device in the top toolbar, then select Custom Size. Enter any pixel width × height and an optional label. Custom sizes are stored in localStorage.

Persistence

Device selection, orientation, zoom, workspace theme, compact mode, and the last URL are stored in localStorage under the key rwp:v1.

The workspace is an open infinite canvas — there are no fixed columns or page boundaries. Device frames can be freely positioned, the view can be panned in any direction, and zoom level is adjustable.

Canvas Navigation

• Pan — Click and drag the canvas background
• Zoom — Scroll wheel, or use the zoom control in the toolbar
• Drag devices — Click and drag a device header to reposition it

Canvas Toolbar Controls

• Refresh All — Reloads all active iframes simultaneously
• Add Device — Opens preset selector or custom-size dialog
• Zoom All to Fit — Scales all devices proportionally to fit the window
• Reset Layout — Returns devices to default arrangement
• Compact Layout — Tiles devices closely together
• Dark / Light Theme — Toggles workspace canvas theme

Minimap

A minimap in the corner provides a bird's-eye overview of where all device frames are positioned relative to the viewport.

Synchronized interactions mirror scroll positions, clicks, and navigation events across compatible viewport frames.

How It Works

A sync-bridge script (/sync-bridge.js) is injected into each iframe. When an interaction occurs in one viewport, it sends a postMessage event; the other viewports receive and mirror it.

Supported Interactions

• Scroll position synchronization
• Link navigation within the site (same-origin, where policies allow)
• Basic click events on compatible elements

Limitations

• Cross-origin iframes may block postMessage — synchronization is limited or unavailable
• Mobile and desktop DOM structures may differ significantly (e.g. a hamburger menu exists at mobile but not desktop)
• Authentication-dependent UI, modals triggered by JavaScript, and hover states are not reliably synchronized
• Sites that detect iframe embedding and redirect will not synchronize

Enabling / Disabling

Use the Sync Toolbar in the workspace to toggle synchronized interactions on or off per session.

Site Shows Blank or Error

Most commonly caused by the target website sending embedding-prevention headers:

• X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN
• Content-Security-Policy: frame-ancestors 'none'

Responsivelyonline detects these via /api/check and displays the exact header rather than showing a broken frame. Use Open in New Tab for non-embeddable sites.

HTTP Errors (403, 404)

These are real HTTP responses from the target server — not embedding issues. A 404 means the URL path does not exist. A 403 means the server denied access.

Localhost Not Loading

In production deployments, private and loopback addresses are blocked by /api/check. Run npm run dev locally, or set ALLOW_PRIVATE_HOSTS=true in a self-hosted production build.

Mixed Content Warning

A secure (https) page cannot embed a non-secure (http) iframe. If you're previewing on an https deployment, the target site must also be https.

Screenshots Not Working

Screenshots use the Screen Capture API — your browser will ask you to select a tab to capture. Choose This Tab. Chrome and Edge support precise Region Capture; other browsers crop by position and require the preview to be fully visible. Safari and most mobile browsers do not support this API.

The FAQ covers general questions, iframe embedding, device emulation, canvas controls, synchronized interactions, privacy, and community support.

Responsivelyonline is open source. Contributions are welcome and reviewed on GitHub.

Ways to Contribute

• Report bugs via GitHub Issues with reproduction steps
• Submit new device presets (name, width, height) as pull requests
• Improve documentation or add usage examples
• Fix accessibility issues or improve keyboard navigation
• Submit performance improvements or canvas enhancements

Getting Started

1. Fork the repository on GitHub
2. Run npm install && npm run dev
3. Make your changes in a dedicated branch
4. Run npm run typecheck to verify TypeScript
5. Open a pull request with a clear description

When filing a bug report, include:

• The URL you were previewing (if relevant)
• Steps to reproduce the issue
• Expected vs. actual behaviour
• Browser name and version (e.g. Chrome 128)
• Operating system (e.g. Windows 11, macOS 14)
• Any relevant browser console errors (F12 → Console)