SEO and structured data for PWAs
Published
A PWA distributed as a website is indexed like any other site; its manifest and service worker
add nothing to that indexing. MDN’s installability guide calls this “making it discoverable through web search”.
Add a WebApplication JSON-LD block to each public page, generated from the same data as its
visible HTML. Validate it with Google’s Rich Results Test and fail the build if it stops parsing.
You need pages that render their primary content as HTML (server-rendered or prerendered),
a public URL per page, and access to the <head> template.
Choose the schema.org type and properties
Section titled “Choose the schema.org type and properties”schema.org defines WebApplication under Thing > CreativeWork > SoftwareApplication > WebApplication. Its own property is browserRequirements, described as “Specifies browser
requirements in human-readable text. For example, ‘requires HTML5 support’”. The useful
properties come from SoftwareApplication: applicationCategory, operatingSystem,
screenshot, softwareVersion, featureList, and offers (inherited from CreativeWork)
for a free or paid app. Use the values your manifest already holds so that name,
description, and the screenshot URLs cannot drift from what the install UI shows.
Emit the JSON-LD from the manifest data
Section titled “Emit the JSON-LD from the manifest data”Google Search Central recommends JSON-LD because it is “less prone to user errors” than
Microdata or RDFa and accepts it “in a <script> tag in the <head> and <body> elements”.
In the page template, serialise one object per page:
<script type="application/ld+json">{ "@context": "https://schema.org", "@type": "WebApplication", "name": "Field Notes", "url": "https://notes.example/", "description": "Offline-first notes that sync when you are back online.", "applicationCategory": "ProductivityApplication", "operatingSystem": "Any", "browserRequirements": "Requires JavaScript and a browser with service worker support.", "screenshot": "https://notes.example/screenshots/desktop-wide.png", "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }}</script>Google’s general guideline applies to every property: “don’t add structured data about
information that is not visible to the user, even if the information is accurate”, and
“Don’t create blank or empty pages just to hold structured data”. A screenshot that the
page does not display, or a description that differs from the visible one, is a guideline
violation even when the facts are right.
Keep the content crawlable without the service worker
Section titled “Keep the content crawlable without the service worker”The crawler does not run your service worker, so a page whose content only appears after a cached shell boots is indexed as the empty shell. Render the article, product, or note body into the HTML response and let the service worker cache that same response. Google states it “can read JSON-LD data when it is dynamically injected into the page’s contents”, so a client-side injection is tolerated for the markup itself, but a static block in the response removes the dependency on JavaScript execution during rendering.
Validate with the Rich Results Test and a build check
Section titled “Validate with the Rich Results Test and a build check”Open the Rich Results Test, paste the public URL under Enter a URL to test or switch to Code and paste the HTML, and run it. The result lists detected items and any parse or required-property errors. Add a check to the build that parses each emitted block so a template bug fails before deploy, before it can appear in Search Console:
import { readFile } from 'node:fs/promises';
export async function assertJsonLd(htmlPath) { const html = await readFile(htmlPath, 'utf8'); const blocks = [...html.matchAll(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g)]; if (blocks.length === 0) throw new Error(`${htmlPath}: no JSON-LD block`); for (const [, json] of blocks) { const data = JSON.parse(json); // throws on a broken template if (data['@type'] !== 'WebApplication') throw new Error(`${htmlPath}: unexpected @type ${data['@type']}`); }}JSON.parse catches malformed output; it does not check schema.org vocabulary, which is
what the Rich Results Test does, so run both.
See also
Section titled “See also”- Make it installable
screenshotsmanifest memberdescriptionmanifest member- Introduction to structured data markup in Google Search (developers.google.com)
- WebApplication (schema.org)