DEV Community

Cover image for I built WIDTHSCAN to find the exact viewport widths where websites break
PowerBuilderr
PowerBuilderr

Posted on Edited on

I built WIDTHSCAN to find the exact viewport widths where websites break

#showdev #webdev #testing #opensource

Responsive bugs do not always appear at standard device presets.

A page may look correct at 375px and 768px while breaking somewhere between them. Finding that exact transition manually can mean resizing DevTools one pixel at a time, inspecting the document width, and trying to identify which element escaped the viewport.

I built WIDTHSCAN to automate that investigation.

Have a public frontend project? Leave its URL in the comments. I’ll personally scan the first five sites and send each owner the result — no installation required. If the report is useful, I’ll then ask you to run WIDTHSCAN once yourself and tell me how the experience went.

What WIDTHSCAN does

WIDTHSCAN is an open-source, local-first responsive QA CLI.

It scans a local or deployed website across a configurable viewport-width range, observes responsive failures, and narrows the detected transitions to exact inclusive ranges.

The initial v0.1.0 release focuses on two detector types:

  • HORIZONTAL_OVERFLOW — reachable document-level horizontal overflow;
  • CLIPPED_TEXT — visible, meaningful text clipped by its own container.

Each scan creates:

  • a standalone HTML report;
  • machine-readable JSON results;
  • annotated screenshots;
  • likely offending elements;
  • a copyable fix prompt for a developer or coding agent.

The report works directly from the local filesystem. WIDTHSCAN does not require an account, cloud service, telemetry, or an external API.

Why exact ranges matter

A report such as 412–427px means the failure was observed at every refined width from 412px through 427px.

That is more actionable than saying that a page “has a mobile issue.” It provides concrete boundaries to reproduce before a fix and verify afterward.

WIDTHSCAN also distinguishes scan-bounded ranges. For example, ≤320–338px means that the issue was already present at the configured minimum of 320px, so the true lower boundary remains unknown.

Initial field testing

I tested WIDTHSCAN on five small public portfolio sites and manually reviewed the findings in Chromium.

The results included:

  • three confirmed horizontal-overflow defects;
  • one clean scan;
  • one intentionally moving element that could be excluded with --ignore.

Intentional overflow is important. Marquees, decorative animation fields, and reveal effects may deliberately place content outside a component.

WIDTHSCAN therefore supports repeatable CSS-selector exclusions:

npx widthscan https://example.com --ignore ".logo-marquee__track"
Enter fullscreen mode Exit fullscreen mode

An element should only be ignored after manually confirming that its behavior is intentional and is not causing a real page-level failure.

I also scanned Arizo Studio with permission from its owner. WIDTHSCAN checked 101 viewport widths from 320px through 1920px, and neither detector produced a finding.

A clean scan is evidence that the available detectors did not find a failure. It is not proof that the website is completely responsive, accessible, or standards-compliant.

Try it on your project

Requirements:

  • Node.js 20 or newer;
  • npm;
  • Playwright Chromium.

Install the browser dependency:

npx playwright install chromium
Enter fullscreen mode Exit fullscreen mode

Run WIDTHSCAN without a global installation:

npx widthscan@0.1.0 "https://example.com" --min 320 --max 1920 --height 900 --out widthscan-report
Enter fullscreen mode Exit fullscreen mode

On Windows PowerShell, open the report with:

Start-Process .\widthscan-report\index.html
Enter fullscreen mode Exit fullscreen mode

On macOS:

open ./widthscan-report/index.html
Enter fullscreen mode Exit fullscreen mode

On Linux:

xdg-open ./widthscan-report/index.html
Enter fullscreen mode Exit fullscreen mode

The same command can scan a local development server:

npx widthscan@0.1.0 "http://localhost:5173"
Enter fullscreen mode Exit fullscreen mode

I’m looking for five early testers

I would like five frontend developers to run WIDTHSCAN on one real project.

The test should take approximately 5–10 minutes. I am especially interested in these questions:

  1. Did installation work on the first attempt?
  2. Was the detected behavior a real defect, intentional behavior, or a false positive?
  3. Was the HTML report understandable?
  4. What was the most confusing or inconvenient part?
  5. Would you use WIDTHSCAN again before releasing a frontend project?

Short answers are welcome.

Repository:

https://github.com/PowerBuilderr/WIDTHSCAN

Feedback Issue:

https://github.com/PowerBuilderr/WIDTHSCAN/issues/1

Feedback can be written in English or Russian. If installation fails, that is valuable feedback too.

Top comments (0)