vibecheck0.3.0
Web essentialsweb-essentialsviewporterror

Missing viewport meta tag in Next.js

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 Next.js

Next.js App Router owns the viewport through the dedicated viewport export (do not hand-write the tag — Next injects it). Export it from any layout or page; it merges with the document head automatically.

app/layout.tsxtsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
}

Next.js docs →

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.