Search by

automattic / jetpack-seo

automattic

Jetpack SEO — the visibility command center for WordPress sites in the agentic web.

Package info

github.com/Automattic/jetpack-seo

Type:jetpack-library

pkg:composer/automattic/jetpack-seo

Statistics

Installs: 2 281

Dependents: 1

Suggesters: 0

Stars: 0

v0.12.0 2026-11-16 15:48 UTC

README

The visibility command center for WordPress sites in the agentic web — a unified wp-admin screen that consolidates SEO, sitemaps, AI discoverability, and site verification settings across all site types (self-hosted, Atomic/WoW, Simple).

This package is built up across a stacked series of PRs (see #48154 for the split plan). It currently provides, on a wp-admin page registered at admin.php?page=jetpack-seo (gated on the seo-tools module being active):

  • Overview — a dashboard with Site visibility, Site verification, AI access, and Content SEO cards. Visibility reports indexing directly and the sitemap by its effective state; verification lists Google, Bing and Facebook plus any other service the site has verified with. AI access summarizes the crawler groups and llms.txt, or the one reason per-crawler settings can't apply. Content SEO shows factual coverage rings (schema, SEO title, meta description, search visibility) with literal counts, each deep-linking to the content still missing that field. The visibility/verification cards deep-link into the matching Settings sections, AI access into the GEO tab.
  • Settings — search-engine indexing, the XML sitemap (with a "View sitemap" link whenever it's on, and turning it off removes the site's sitemap entirely — including WordPress core's own — for a proper 404; the toggle is disabled while indexing is blocked, since a sitemap can't be served then), canonical URLs, the title structure for all page types (front page, posts, pages, tags, archives), the front-page description, site verification codes, and a single site-level Schema module (a BreadcrumbList toggle plus the site's Organization details, with LocalBusiness nested as a refinement of the Organization and one Save for both), plus the signed-in user's Author profile card, and search & social previews of the home page (Google / Facebook / X), with a Media Library picker for the default share image. Content-specific and Social-selected images take precedence over the default. SEO tools is turned off from My Jetpack › Features, not from this page; while it's off the Jetpack › SEO menu item is hidden, like other Jetpack modules. New sites get it on at their first connection, since the module auto-activates; existing sites keep their setting.
  • Content — a DataViews list of published content across every supported post type, showing each item's SEO state (schema type, meta description set, search visibility). Rows link to the Gutenberg editor and open a per-post SEO inspector (custom title, description, schema type, noindex, SERP preview) in the dashboard sidebar. Filters for post type, schema type, description state, and search visibility run client-side over the merged set. The Schema type control and SEO columns also appear in the block editor and edit.php post-list tables respectively; the post-list columns are hidden by default and opted into per user via Screen Options. JSON-LD (Article / FAQ) is emitted on wp_head.
  • GEO — llms.txt generation, the plan-gated AI SEO Enhancer, and per-crawler allow/block controls for answer engines and training crawlers (written to the virtual robots.txt). (Generative Engine Optimization; internal route/id ai.)

Architecture

Built as a @wordpress/build (wp-build) dashboard, the pattern shared by recently-shipped Jetpack admin pages (Podcast, Scan, Forms, Newsletter):

  • PHP: Automattic\Jetpack\SEO\Initializer boots the package on supported hosts (excluding VIP) and applies its discoverability cohort; Admin_Page registers the admin menu via Admin_Menu::add_menu(), loads wp-build's generated bundle (build/build.php + WP_Build_Polyfills::register()), and bootstraps the app's initial state. Because the user-facing slug (jetpack-seo) differs from wp-build's page slug (jetpack-seo-dashboard), the screen id is aliased on current_screen so wp-build's auto-generated enqueue callback fires.
  • React: an ES-module bundle. Each top-level view (Overview, Content, GEO, Settings) is its own @wordpress/route route under routes/, exporting a stage — the per-route pattern shared with Forms. The Content route also exports an inspector (the per-post SEO editor), rendered in wp-build's native Stage/Inspector sidebar when a post is selected (?postId=). A shared shell (_inc/dashboard/dashboard-page + dashboard-nav) renders the AdminPage chrome from @automattic/jetpack-components and the route-based tab navigation, so every route gets the same header, tabs and footer. UI uses @wordpress/components, @wordpress/ui, and @wordpress/icons.
  • Data: the Overview, Settings, and GEO routes are backed by read-only REST routes GET /jetpack/v4/seo/{overview,settings,geo} (Dashboard_Data::register_rest_reads(), manage_options-gated), whose responses are preloaded into the page server-side via rest_preload_api_request() (Admin_Page::inject_script_data(), on the jetpack_admin_js_script_data filter — wp-build pages load as ES modules, so wp_localize_script can't bootstrap them and the script-data layer is the supported channel). On a normal load each route reads its slice from the preload synchronously through @automattic/jetpack-script-data (_inc/data/get-preloaded.ts) — instant, no request. When a slice is missing or stale (e.g. a mismatched bundle after an update), the route's stage fetches it from its REST route instead of dead-ending: _inc/data/use-ensure-tab-data.ts shows a loading skeleton, retries silently, and surfaces a recoverable "Try again" state only on genuine failure. google_verify and site stay synchronous on window.JetpackScriptData.seo. The Content route fetches posts and pages live from core /wp/v2/posts and /wp/v2/pages (no custom endpoint), with SEO meta returned via registered show_in_rest post meta; the inspector writes through the same core post endpoint. Every Settings and GEO write that is a plain option goes through core /wp/v2/settings — each is registered with show_in_rest in Dashboard_Data::register_rest_settings(), so the dashboard needs no Jetpack-plugin route and behaves identically on WordPress.com and self-hosted. Two kinds of write can't live there and get package-owned routes: the settings whose write switches a Jetpack module (sitemap, canonical URLs, site verification — POST /jetpack/v4/seo/modules), because switching a module can fail and core's settings endpoint has no way to refuse a value, and the nested site-level schema settings (GET/POST /jetpack/v4/seo/schema-settings), so each schema section can be preserved across partial updates. The signed-in user's Author profile also has its own route (GET/POST /jetpack/v4/seo/author-profile), because WordPress.com Simple's API drops user fields from core's /wp/v2/users; for WordPress.com accounts it leaves name, bio and website to the account and saves only the job title and social profiles. The Settings form writes the settings and module endpoints sequentially, never in parallel, and re-reads /jetpack/v4/seo/settings after every save so the form shows what the server actually stored rather than what it was asked to store.
  • Availability: existing non-AI SEO controls and output do not require a paid plan. The product availability switch, module activation, capabilities, privacy, host limitations and plugin-conflict safeguards still apply. AI SEO retains its existing entitlements and request allowances.
  • Tracks: every event goes through recordSeoEvent() (_inc/data/record-seo-event.ts), which adds the identifiers Admin_Page::get_tracks_context() bootstraps plus surface and the calling screen, which is the tab id. The server sends that context only when Admin_Page::can_use_analytics() passes, and the client records nothing without it. @automattic/jetpack-analytics only queues events; Admin_Page::enqueue_tracks_transport() loads the w.js that sends them.

Saving settings

Option-backed settings save through /wp/v2/settings. Clearing a front-page description also removes superseded legacy text, including when the modern option is already empty or absent. Invalid non-empty verification input preserves the saved code; an empty string deliberately clears it.

Sitemap, canonical URL, and verification switches use /jetpack/v4/seo/modules and read live module state. No duplicate sitemap or canonical options are written. On platforms without those modules, sitemap and canonical controls are read-only and verification codes remain editable. WordPress.com Simple is the exception for canonical URLs: it has no modules, so the same route saves its switch to the jetpack_canonical_urls_enabled option (off when missing), and Canonical_Urls loads the Jetpack plugin's canonical-urls module file, which prints the archive canonical tags. Simple's platform sitemap is unchanged.

On private and coming-soon Atomic sites, module writes temporarily bypass wpcomsh's output-suppression filter. The original filter is restored after the switch, so a saved preference never publishes the site or enables private sitemap output.

UI conventions

Text hierarchy

@wordpress/ui's Text variants are easy to pick wrong, because the heading and body ramps don't share a scale — heading-sm is smaller than body-md. Resolved from the WPDS tokens (@wordpress/theme):

Variant Size Weight Transform Use it for
heading-lg 15px medium — card title
heading-md 13px medium — sub-heading inside a module
heading-sm 11px medium UPPERCASE field label
body-md 13px regular — body copy
body-sm 12px regular — field explainer

"Small heading" is a field label, not a small sub-heading. Reach for heading-md when you want a sub-heading.

The rule for prose, which the modules drifted away from once already:

  • body-md — a module's or section's own prose. Things the reader is meant to read.
  • body-sm + .muted — explainer text attached to a field: hints under an input, help under a group label. Not general copy.
  • body-md + .muted — the third case, and deliberately narrow: chrome inside the SERP and social preview mockups (social-previews-card, serp-preview). Those imitate how Google and Facebook render a link, so their type follows someone else's design, not ours. Don't extend this case to real UI.

Field labels should be uppercase across the board. Where a TextControl renders the label, that's automatic; where a label is drawn by hand, use heading-sm so it matches (same size and casing — the control label is weight 600 against heading-sm's medium, so they read alike without being pixel-identical).

Element rendering

Text renders a <span> by default, which is rarely what you want:

  • Prose → render={ <p /> }.
  • A real sub-heading → render={ <h3 /> }. Card headers are h2 (the page <h1> is in Admin_Page), so a module's own sub-headings are h3. Without this a screen-reader user navigating by heading finds the card title and nothing beneath it.
  • A hand-drawn field label heading a group of controls rather than one input → keep it a span, but give the wrapper role="group" and aria-labelledby pointing at it (see google-verification-field), or it announces as a label attached to nothing.

Rendering as <p> or a heading is safe: Text always applies both of @wordpress/ui's global-CSS defenses, and every variant defines --_gcd-heading-* alongside --_gcd-p-*, so the element change doesn't alter the type.

Development

# Build once (from the repo root)
jetpack build packages/seo

# Watch mode
pnpm --filter='@automattic/jetpack-seo' run watch

# Typecheck
pnpm --filter='@automattic/jetpack-seo' run typecheck

# Tests
pnpm --filter='@automattic/jetpack-seo' run test

The built JS/CSS lives in build/ and is included in the vendored Jetpack plugin distribution via .gitattributes (/build/** production-include).

IndexNow background delivery

Pending notifications use non-autoloaded options, with stable records for normal post updates and historical URLs. Repeated changes are combined for five minutes before background delivery. Workers recheck visibility, consent, and URL scope, and preserve newer changes when acknowledging older work. Both new admissions and replacements check the queue generation. Results from a worker that predates a queue reset cannot restore old status or cooldowns.

The following filters accept integers:

  • jetpack_seo_indexnow_batch_size: maximum URLs per request, default 100, bounded to 1 through 10,000.
  • jetpack_seo_indexnow_queue_capacity: maximum pending records admitted, default 10,000, bounded to 1 through 50,000.

Normal updates coalesce by post ID, with the current URL resolved during delivery. Old-address and removal notifications retain the exact URL. Existing URL-based records remain readable, and duplicate resolved URLs are sent only once per batch.

Lowering capacity preserves existing entries and allows updates to an already pending record. New records are refused while the queue remains above the admission limit. Simple also refuses additions or growing replacements that would take estimated serialized options storage above 750,000 bytes, leaving headroom for other settings and delivery bookkeeping. Unchanged or smaller records can still be refreshed. Refused notifications are not saved for later replay; post saving continues normally. Overflow is reported separately from delivery status.

Workers read pages of 250 rows and normally inspect at most 5,000 rows per run. Larger configured batches can increase that scan budget. A 1 MiB payload budget, including resolved URLs and rechecked before delivery, can reduce the actual batch size. Workers check a 20-second processing budget between pages. Scheduler delays can extend delivery time.

Disable IndexNow before reverting to a URL-only worker. Older workers discard ID-only records without submitting them, while remaining URL snapshots are still understood. Keep IndexNow disabled on Simple until a version with the storage bound is restored.

HTTP 202 records receipt with ownership verification pending, without consuming retries. HTTP 429 pauses all site submissions and respects Retry-After, with a minimum ten-minute cooldown. Other temporary failures receive bounded backoff, with five retries and a maximum entry age of 48 hours. Permanent failures are dropped, and status counts them apart from records kept for retry. A received or accepted batch clears the admission warning recorded before that batch, without erasing a newer one. Receipt does not establish crawling or indexing. Delivery can repeat after an interruption with an ambiguous response.

IndexNow settings

The Site visibility section has one off-by-default "Notify search engines when content changes" toggle. It does not affect the existing completion badge. Enabling it creates verification automatically and applies only to subsequent eligible content changes. Disabling it clears pending work and obsolete delivery warnings without changing other SEO settings. Dated accepted history is retained for the current site address; pending-verification receipts and former-address history are discarded.

Status distinguishes received notifications awaiting ownership verification from accepted notifications; neither confirms indexing. Receipt times use the site timezone and the locale's default date format. Contextual warnings explain throttling, delayed scheduling, and missed notifications; timing warnings use the server clock and allow an hour of scheduler delay. While delivery is paused, the row shows only the pause reason. Status refreshes when the section opens, the window regains focus, or a settings save settles. Visibility and notification saves cannot overlap, and a refresh preserves unrelated unsaved edits. Delivery limits are configured through the filters above, with no tuning controls in the dashboard.

The notification row only mounts when the backend advertises support; unavailable hosts do not request the status endpoint.

WordPress.com Simple also requires the guarded native route registration before this interface is released. The companion can deploy before the package because it tolerates versions without the controller.

IndexNow metadata reconciliation

Tracked editor saves emit once after the completed save. Standalone metadata changes on previously untracked posts reconcile at request shutdown, using the originating site and the visibility captured before the first write. This avoids announcing a temporary public state between access and noindex changes. At most 1,000 posts can await standalone metadata reconciliation per request; additional candidates are skipped until the pending batch is flushed, while restriction cancellation continues. Long CLI jobs can explicitly call Automattic\Jetpack\SEO\Indexnow_Events::flush_metadata_changes() at completed logical save boundaries; an interrupted process can lose deferred notifications. No historical backfill is performed.