vibecheck0.3.0
Web essentialsweb-essentialsviewporterror

Missing viewport meta tag in React

Without <meta name="viewport">, mobile browsers assume a ~980px desktop canvas and shrink the whole page to fit, so text is unreadable and tap targets are tiny. AI scaffolds often generate the component tree but leave the base HTML document untouched, so this one line never gets added. It is the single biggest reason an otherwise-fine page looks broken on a phone.

Framework fixes
GeneralReactNext.jsVueSvelteVanilla JS

Symptoms

  • Page looks zoomed-out on mobile — everything is tiny
  • Users have to pinch-to-zoom to read or tap anything
  • CSS media queries never fire because the layout viewport is 980px, not the device width
  • Lighthouse flags "Does not have a <meta name="viewport">"

How VibeCheck catches it

In your widget · Problems

errorweb-essentialsMissing viewport meta tag

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "web-essentials", issue: "Missing viewport meta tag", threshold: "No <meta name="viewport"> present in the document head" }

The same string in your widget and in your agent’s context — no screenshot, no copy-paste.

Root causes

  • The framework template (index.html / app.html) was edited to remove it, or a hand-rolled HTML shell never had it
  • Meta tags are managed in a head library but the viewport was never configured
  • A generated single-file export dropped the document <head>

The fix for React

A plain Vite/CRA React app renders into a static index.html. The viewport tag lives there, not in a component — React never touches <head> unless you add a head manager.

index.htmlhtml
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
</head>

Steps

  1. Open your document head (index.html, app.html, or your framework’s metadata config)
  2. Add <meta name="viewport" content="width=device-width, initial-scale=1">
  3. Reload on a real phone or device-emulation and confirm the layout uses the full width

See the general, framework-agnostic fix →

FAQ

Should I set user-scalable=no or maximum-scale=1?
No. Disabling zoom is a WCAG accessibility failure — users with low vision rely on pinch-to-zoom. width=device-width, initial-scale=1 is all you need.
Does Next.js add the viewport tag automatically?
Next injects a sensible default, but you should declare the viewport export explicitly so it is intentional and reviewable. Never hard-code the <meta> tag in Next’s App Router.
Why does my media query not work on mobile without this tag?
Without the viewport tag the layout viewport defaults to ~980px, so min-width/max-width breakpoints compare against 980, not the real device width. The tag makes the layout viewport equal the device width.