wontfit

Find out what won't fit before your users do.

Website · Documentation · PyPI · Changelog

wontfit shows your running web app at phone and tablet widths side by side in the browser you already have open, tells you which element is too wide for a 375px screen, and fails your build when a layout breaks. It works even when the app sends X-Frame-Options or a CSP frame-ancestors directive, and even when your browser window is fullscreen.

• Zero dependencies. Python 3.9+ standard library only. Binds to loopback.
• It names the culprit. Not just "this overflows" but table.compare, 583px too wide. Plus tap targets under 44px, text under 12px, cross-frame inspect and live reload.
• Runs in CI. wontfit check fails the build on overflow; wontfit shoot writes PNGs and a contact sheet for the pull request.

Install

pipx install wontfit       # or: uv tool install wontfit
uvx wontfit --help         # or run it once without installing

wontfit check and wontfit shoot drive a headless browser, which is an optional extra:

pipx install --include-deps 'wontfit[shoot]'
playwright install chromium

Already installed without it? pipx inject --include-apps wontfit playwright, then playwright install chromium.

Every GitHub release carries the same wheel and sdist, and main installs straight from git: pipx install git+https://github.com/InfoDiveLabs/wontfit. Nothing to install at all: clone it and run python3 -m wontfit. The core is standard library only.

Try it in 30 seconds

No app of your own running? The repo ships a fake product site that refuses to be framed and has six planted mobile bugs:

git clone https://github.com/InfoDiveLabs/wontfit && cd wontfit
make showcase        # starts examples/showcase on :3939 and opens the harness

With your own app:

wontfit --upstream http://localhost:3000 --pages /,/pricing --open

See it

	The harness. One column per page x width; each frame carries its own verdict. Layout state lives in the URL, so this is a shareable link.
	Overflow, named. The pricing table is 583px too wide; the culprit list says table.compare and its bounds.
	Tap targets. Press t to outline every interactive element under 44x44 CSS px inside the frame.
	Inspect across frames. Press i, hover an element in one frame, and it is highlighted with its size in every frame; the footer shows the selector.
	Landscape. Swaps width and height. Here the app's fixed header grows to two rows and covers the KPI cards.
	Live reload. Hash a URL or watch files; the footer shows what is watched, the fingerprint and the last change.
	wontfit shoot. A PNG per page x width plus this contact sheet, ready for a pull request.

Why not DevTools device mode, Responsively or Polypane?

DevTools device mode shows one page at one size in the tab you are in. It is fine for a quick look and poor at the loop you are actually in while fixing a responsive layout: three pages at three widths, after every save, without picking a device from a dropdown per tab. It also cannot tell you which element is 40px too wide.

Responsively and Polypane are dedicated browsers that solve the side-by-side problem well, with synced scrolling, device frames and much more. They are also 200-500 MB Electron apps (Polypane is paid), you use them instead of your usual browser and extensions, and they do not run in CI. wontfit is a 2,000-line Python package with no dependencies that puts the widths in the browser you already have open, adds the four diagnostics a mobile layout review actually needs, and ships a check command so the same diagnostics gate a pull request. If you want synced scrolling, device bezels, or emulated touch, use one of those tools; if you want something you can pipx install and forget, this is it.

Features

Configuration

wontfit init        # writes a commented wontfit.toml; commit it
wontfit             # contributors need nothing else

# wontfit.toml
upstream = "http://localhost:5173"
pages = ["/", "/pricing", "/dashboard"]
widths = ["se", "iphone15", "pixel8"]
watch_files = ["src/**/*.css"]
fail_on = ["overflow"]

[cookies]
session = "dev-session"

Keys: upstream, port, pages, widths, height, cookies, headers, watch_url, watch_files, watch_interval, rewrite_host, insecure, out, fail_on. The same table works under [tool.wontfit] in pyproject.toml. --no-config ignores any file. On Python 3.9 and 3.10 a small built-in TOML parser reads the file (strings, numbers, booleans, arrays, tables); 3.11+ uses tomllib.

In CI

pip install 'wontfit[shoot]'
playwright install --with-deps chromium
wontfit check --pages /,/pricing --widths se,iphone15,pixel8 --fail-on overflow --json report.json
wontfit shoot --pages /,/pricing --widths se,iphone15,pixel8 --out shots

page      size     overflow                small taps  text<12px
--------  -------  ----------------------  ----------  ---------
/         375x800  +401px (img.shot)       9           1
/pricing  375x800  +583px (table.compare)  3           1
/terms    375x800  fits                    3           10

FAIL (overflow):
  / @ 375: overflow +401px (img.shot)
  /pricing @ 375: overflow +583px (table.compare)

A complete GitHub Actions job that starts your app, runs check, and uploads the report and screenshots as artifacts is in docs/ci-example.yml; a pre-push hook is in docs/pre-commit-example.yaml.

Your stack

docs/recipes.md (also in the online docs) has copy-paste commands and the one gotcha per framework for Vite/React, Next.js, Nuxt, SvelteKit, Django, Flask/FastAPI, Rails, Go, Laravel, static sites, Storybook and Docker Compose, including how to keep HMR working (its WebSocket does not go through the proxy).

Flags

wontfit [options] starts the proxy and harness.

wontfit check and wontfit shoot take --upstream --pages --widths --height --cookie --header --insecure --no-config --landscape --timeout --settle, plus:

wontfit init [--upstream URL] [--path FILE] [--force] writes the starter config.

Harness shortcuts (when the harness itself has focus): r reload, t tap overlay, i inspect, Esc leave a field. URL keys: p pages, w widths, h height, o=l landscape, live=0.

FAQ

The app sets a CSP. Does wontfit weaken it? Only frame-ancestors is removed. script-src, connect-src, nonces and the rest are forwarded as sent, for Content-Security-Policy-Report-Only too. X-Frame-Options is dropped because it has no other purpose.

Do cookies and logins work? Yes. Browser cookies for 127.0.0.1:8081 are forwarded upstream; upstream Set-Cookie comes back with Domain and Secure removed so it sticks on the proxy's loopback origin (SameSite=None becomes Lax). Log in inside a frame, or pass --cookie session=... / --header 'Authorization: Bearer ...'.

HTTPS upstream? --upstream https://localhost:5173, and --insecure for self-signed certificates. The proxy itself speaks plain HTTP on loopback, which browsers treat as a secure context.

The app redirects to http://localhost:3000/... and leaves the proxy. Absolute Location headers to the upstream origin are rewritten. Client-side redirects built from a hard-coded host cannot be; use --rewrite-host preserve so the app builds URLs from the proxy's Host.

Django ALLOWED_HOSTS / Rails hosts / Vite allowedHosts reject it. They should not: the proxy sends the upstream's own host, and rewrites Origin/Referer to match so CSRF checks pass too.

A frame says "cross-origin". The page inside navigated to another origin (an OAuth provider, say). It still displays; diagnostics need same-origin access and pause for that frame.

Live reload does not fire. The default detector hashes your first page's HTML; a CSS-only change that leaves it byte-identical will not trigger. Use --watch-file 'src/**'.

Why is a plain text link counted as a small tap target? Anything interactive under 44x44 CSS px counts (WCAG 2.5.5, Apple HIG). Inline links usually trip it, which is why it is a count, not a red flag, and not in the default --fail-on.

What it deliberately does not do

• WebSockets. Upgrade: websocket gets a 501. See the recipes for keeping your framework's HMR client pointed at the dev server.
• HTTP/2, server push, trailers, connection pooling. HTTP/1.1, one fresh upstream connection per request.
• Rewriting bodies. HTML, JS and JSON pass through byte-for-byte.
• Binding to anything but 127.0.0.1.

Security note

wontfit strips framing protection from whatever you point it at and has no authentication, so it binds to 127.0.0.1 only. Never expose the port on a network interface, through a tunnel, or via a container port mapping. To preview on a real device, use your app's own dev server on the LAN.

Development

python3 -m unittest                 # tests, stdlib only
make lint                           # ruff, if installed
make showcase                       # the Ledgerly demo site + harness
PY=.venv-shots/bin/python make screenshots   # regenerate docs/images (needs playwright, pillow)

See CONTRIBUTING.md and CHANGELOG.md.

License

MIT. Built and maintained by InfoDive Labs. Bug reports and pull requests are welcome in issues.