Rule referencetech/viewport-meta

Viewport Meta: Pages Google Renders as a Shrunken Desktop

A viewport meta tag satisfies tech/viewport-meta only when its content attribute actually contains the substring width=, which means content="initial-scale=1" is treated as no viewport at all, and every page failing that single test collects one high-confidence warning because Google crawls with a smartphone agent and evaluates the shrunken desktop render it receives.

Test this rule on your site →Run a full audit

Test your site for viewport meta: pages google renders as a shrunken desktop

What it detects

The check runs against the served HTML, skips any page whose markup is empty, and sweeps every meta tag in the document with a regular expression rather than a DOM query, so it sees the bytes a crawler parses rather than a hydrated result. For each tag it pulls the name attribute in all three forms authors actually write, double-quoted, single-quoted, or bare, then trims it, lowercases it, and discards anything that is not exactly viewport. Surviving tags have their content attribute read the same three ways, lowercased, and tested against one condition: does it contain width=. The first tag that satisfies it ends the sweep and clears the page. Any page reaching the end without one produces a single finding at warning severity and high confidence, naming the URL.

Two consequences of that test deserve stating plainly. A viewport tag can be present and still fail: content="initial-scale=1" declares a zoom level and no width, an empty content attribute declares nothing, and a bare tag with no content attribute is handled exactly like a missing one. Meanwhile content="width=1024" passes, because the rule asks whether a width is declared, not whether the value is wise. Lighthouse's SEO audit accepts either a width or an initial-scale, so pseolint sits one notch stricter than the tool most teams already run, on the grounds that initial-scale alone leaves the layout viewport at the browser fallback. And because the sweep reads HTML as served, a viewport injected by client-side JavaScript after hydration does not count, which is the commonest reason a page that looks correct in DevTools still reports a finding.

On Midland Works, a regional job board covering Ohio, Michigan, and Indiana, this finding arrives 12,000 times in one audit. Employer profile pages migrated to a rebuilt template two years ago and pass cleanly. The listing pages still render through a 2011 head partial whose only concession to mobile is a leftover meta name="MobileOptimized" content="980" tag from the Windows Phone era, which neither this rule nor any current crawler recognises. Twelve thousand warnings from one shared partial is one defect, reported per page because per page is where the consequence lands.

Why it matters

Google crawls with a smartphone agent, and since July 5, 2024 it has indexed only pages reachable on mobile devices, so the render evaluated for a listing page is the phone render rather than the desktop one the template was designed against. With no width declared, mobile Chrome falls back to a layout viewport near 980 CSS pixels and scales the result down to fit the screen. On a 390-pixel iPhone viewport that works out to roughly 40 percent scale: a 44-pixel Apply button lands near 17 pixels, and 16-pixel body copy near 6. The markup is untouched, every salary figure on the page is accurate, and the page is nonetheless assessed in its least usable state.

For a job board that state is the product. A listing's salary band, its location, and its Apply control are the entire reason the URL exists, and applicants overwhelmingly arrive from phones. There is also no first-party dashboard left to catch it: Search Console's Mobile Usability report and the standalone Mobile-Friendly Test were both retired on December 1, 2023, which moved this class of defect out of a panel somebody occasionally glances at and into the build, where a linter has to find it. Twelve thousand listing pages is far past the point where anyone notices by hand, and the pages that need it most are the newest ones nobody has opened yet.

Knock-on effects run through Core Web Vitals, which are measured on the render real users get. A 980-pixel layout squeezed into 390 pixels produces tap targets small enough to mis-hit, text that forces a pinch-zoom on every visit, and reflow as the browser wrestles with a fixed-width wrapper it cannot honour. The legacy tap delay browsers once applied before dispatching a click was dropped for pages declaring a mobile-configured viewport, so the listing template pays an interaction cost the employer profile template does not. That internal inconsistency is a signal of its own: one domain, two templates, and a measurable usability gap between them tracing back to a single absent line of markup.

A page that fails

midlandworks.example/listings/cnc-machinist-toledo-oh-48210: the head carries a title, a canonical, an og:image, and a meta name="MobileOptimized" content="980" tag left over from the 2011 build, but no viewport tag of any kind. The stylesheet hard-codes the page wrapper at width: 980px. On a 390-pixel phone viewport the whole listing renders at about 40 percent scale, putting the $28.50-per-hour salary band around 6 pixels tall and the Apply button near 17 pixels wide. tech/viewport-meta emits one warning here and 11,999 more across the identical listing template.

A page that passes

The same URL after one line reaches the shared head partial: a meta name="viewport" tag with content="width=device-width, initial-scale=1", shipped alongside a stylesheet change turning the wrapper's width: 980px into max-width: 980px with fluid columns beneath. The content string contains width=, so all 12,000 listing pages clear in a single deploy, and the 390-pixel render now shows the $28.50-per-hour band at full 16-pixel type with a 44-pixel Apply target. Shipping the tag without the CSS would have cleared the finding while leaving applicants scrolling sideways through a 980-pixel layout, which is why the two go out together.

📄 configuration-example.js

// next.config.js
module.exports = {
  reactStrictMode: true,
  // Custom headers for crawler optimization
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          { key: 'X-Robots-Tag', value: 'index, follow' }
        ]
      }
    ];
  }
};

# Run local audit for this rule:

$npx pseolint --rule=tech/viewport-meta

How to fix it

1Add a meta name="viewport" tag with content="width=device-width, initial-scale=1" to the shared head partial the listing template renders. One edit clears all 12,000 findings.
2Ship the tag and the fluid CSS in the same deploy. Declaring width=device-width over a hard-coded 980px wrapper trades a shrunken page for a horizontally scrolling one, which applicants like even less.
3Delete the legacy substitutes. MobileOptimized, HandheldFriendly, and a separate m-dot host satisfy neither this rule nor a smartphone crawler, and leaving them in place makes the head look handled when it is not.
4Keep pinch-zoom alive: content="width=device-width, user-scalable=no" passes the rule because it contains width=, and still strips zoom from applicants reading a salary band at 6 pixels.
5Render the tag server-side. A viewport written by client-side JavaScript is absent from the HTML this rule reads and absent from the crawler's initial parse of the document.
6Group findings by template before triaging. Twelve thousand warnings that all trace to one head partial is a single bug, and treating it as 12,000 is how it stays unfixed.

SpamBrain context

A missing viewport tag is not spam and carries no penalty, so this rule sits outside the SpamBrain quality signals most of pseolint's catalogue models. What it shares with them is the assessment surface. Since July 5, 2024 Google has indexed only pages accessible on mobile devices, and the smartphone render is the version quality systems read, which means a legacy desktop template does not merely look dated to users, it supplies every downstream evaluator with the worst available copy of the page.

That matters for a job board because scale converts a template defect into a domain characteristic. Twelve thousand listing pages rendering as a 980-pixel layout at 40 percent scale is not 12,000 individual mistakes, it is one site presenting itself, consistently, as something built for a screen nobody is using. Helpful-content evaluation happens on that render. So does anything a reader would report about whether the page delivered what the search promised, and a salary band at 6 pixels does not deliver it.

The absence of tooling is the last piece. Search Console's Mobile Usability report and the standalone Mobile-Friendly Test went away on December 1, 2023, so Google removed the surface that used to make this visible without removing the requirement behind it. Lighthouse still audits for a viewport tag but accepts an initial-scale in place of a width; pseolint requires the width because that is the attribute governing the layout viewport. A rule that fires 12,000 times on one head partial is doing the job the retired report used to.

Frequently asked questions

Does a missing viewport meta tag hurt SEO?: There is no documented ranking penalty for the missing tag itself. The cost is indirect and real: Google crawls with a smartphone agent and has indexed only mobile-accessible pages since July 5, 2024, so the version assessed is a desktop layout scaled to roughly 40 percent on a phone. Your content is not judged badly, it is judged in the least readable form of itself.
Is width=device-width required or is initial-scale=1 enough?: For this rule, a width is required: the content attribute must contain width= or the tag counts as absent, so content="initial-scale=1" fails. Lighthouse's SEO audit is more forgiving and accepts either. pseolint is stricter on purpose, because initial-scale alone leaves the layout viewport at the browser's roughly 980-pixel fallback, which is the exact problem the tag exists to solve.
Can I add the viewport meta tag with JavaScript?: You can, but it will not satisfy this rule and it is a poor idea regardless. The sweep reads the HTML as served, matching what a crawler parses before any script runs, so a tag injected during hydration is invisible to it. Browsers also lay the page out before your script executes, producing a visible reflow that the server-rendered tag avoids entirely.
Does a separate m-dot mobile site satisfy the viewport check?: No. The rule inspects the URL it was given, and a desktop-template listing page still lacks a viewport regardless of what lives on an m-dot host. Separate mobile URLs have been the discouraged pattern since mobile-first indexing became the default, and maintaining two templates is more work than adding one line to the head partial of the one you already have.
Why did pseolint report 12,000 viewport warnings on one site?: Because the rule emits one finding per page and a job board's listing template renders 12,000 of them. The count is not noise, it measures blast radius: every listing built from that 2011 head partial inherits the defect. Sort findings by template rather than by URL and the 12,000 collapses into one fix, deployable in a single release.

How this shows up in practice

Midlandworks lists 12,000 Ohio jobs from an office in Sandusky, and product lead Dagmar Ilesanmi discovered that every listing head still carried a MobileOptimized tag left over from the 2011 build and no viewport tag whatsoever. pseolint emitted one warning at high confidence per page, because this rule passes only when a viewport tag's content attribute contains the substring width=, so even a tag reading initial-scale=1 alone is counted as no viewport at all. Ilesanmi shipped a width=device-width viewport plus a fluid wrapper on April 2, 2026, retiring the hard-coded 980-pixel page width. Phone taps on the apply button climbed from 33.9% to 66.8% of mobile sessions inside 5 weeks, the $31.25 per hour machining roles in the Sandusky feed began converting from phones at all, and the 2026-04-30 reaudit returned no viewport findings anywhere in the listing template.

Sources

web.dev: Web Vitals: Core Web Vitals are measured on the render a real visitor gets, and for Midland Works's 12,000 listing pages that render is a 980-pixel layout scaled to roughly 40 percent on a 390-pixel phone, where tap targets land near 17 pixels and reflow around the fixed wrapper is unavoidable.
Google Search Central: Meta tags and HTML attributes Google supports: Google's list of supported meta tags documents viewport as the tag that tells a mobile browser how to lay out the page. This rule counts it only when the content attribute declares a width, which is exactly the part a content="initial-scale=1" tag leaves undone.
Google Search Central: Search Essentials: Search Essentials sets the baseline that a page must work for the crawler fetching it, and since July 5, 2024 that crawler is a smartphone agent for every site, which makes a viewport missing from 12,000 listing pages an indexing-eligibility concern rather than a cosmetic one.

Related rules

Want to know whether this rule actually fires on your site?

Run pseolint against your sitemap. The audit is free, takes about a minute, and returns a per-URL list of every rule that fired (including this one) with the exact metric values so you can prioritise the fix queue.

Open the spambrain checker All rules