Skip to content

Advertise the UCP profile with a <link rel="ucp"> tag in ShopifyScripts - #4154

Open
mdamjanic7 wants to merge 5 commits into
mainfrom
misha/ucp-discovery-link-tag
Open

mdamjanic7 wants to merge 5 commits into
mainfrom
misha/ucp-discovery-link-tag

Conversation

@mdamjanic7

@mdamjanic7 mdamjanic7 commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

WHY are these changes introduced?

Agents and link-preview services that read a storefront's HTML need a way to tell that the site supports UCP (Universal Commerce Protocol) and where its profile is. Liquid storefronts already render a <link rel="ucp"> tag in the page head. Hydrogen storefronts don't.

WHAT is this pull request doing?

getShopifyScriptTags() now includes this link, so every framework's ShopifyScripts renders it in <head>:

<link rel="ucp" href="/.well-known/ucp">
  • No version attribute. Agents get the latest stable profile, and old Hydrogen releases never advertise an outdated version. This matches Oxygen's Link header.
  • Internal, always on. No new option.
  • Types stay backwards-compatible. ShopifyLinkTagAttributes only adds "ucp" to rel. Type tests check that existing consumer code still compiles.
  • The browser never fetches it. Browsers ignore unknown link types. I checked React 19, Unhead (Nuxt), Solid, Svelte and Astro, and none of them treat it specially.
  • No template changes needed. Every template and example already renders ShopifyScripts link descriptors in <head>.
  • Rendered on *.myshopify.dev too. Those Oxygen deployment URLs don't serve the profile. Some frameworks build these tags without a request (SolidStart once per server, Next.js when prerendering), so skipping them would need a new hostname option. A 404 there is harmless.
  • Known gap: error pages. Fallback heads that don't render ShopifyScripts don't get the tag: root-loader failures in React Router and the Hydrogen example, Next's global-error.tsx, and Nuxt's error.vue. Agents find it on any normal page.
  • Docs. The hydrogen-setup runtime-scripts step mentions the link, where the profile is served, and asks you to confirm the link appears in the server-rendered <head>.

Off Oxygen, /.well-known/ucp is served by handleShopifyRoutes once #3976 lands, so the two should ship in the same release. The Link response header is added in #4153.

HOW to test your changes?

  1. pnpm --filter @shopify/hydrogen test. The core, React and Vue ShopifyScripts tests check that the link renders exactly once with only rel and href.
  2. Run the React Router template, then curl -s localhost:5173/ | grep 'rel="ucp"'. You should see one <link rel="ucp" href="/.well-known/ucp"/> in <head>.
  3. In the browser's Network panel, there is no request to /.well-known/ucp.

Locally I confirmed the tag in server-rendered HTML from:

  • the React Router and Next.js templates,
  • the Nuxt and SolidStart examples,
  • Svelte's server renderer, using the SvelteKit example's head pattern.

The Hydrogen and Astro examples share those render paths, but need example secrets to run.

Post-merge steps

Release together with or after #3976.

Checklist

  • I've read the Contributing Guidelines
  • I've considered possible cross-platform impacts (Mac, Linux, Windows)
  • I've added a changeset if this PR contains user-facing or functional changes. Test changes or internal-only config changes do not require a changeset.
  • I've added tests to cover my changes
  • I've added or updated the documentation

@mdamjanic7
mdamjanic7 requested a review from a team as a code owner October 8, 2026 16:58
@shopify

shopify Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Oxygen deployed a preview of your misha/ucp-discovery-link-tag branch. Details:

Storefront Status Preview link Deployment details Last update (UTC)
Skeleton (skeleton.hydrogen.shop) ✅ Successful (Logs) Preview deployment Inspect deployment November 12, 202611:48 AM

Learn more about Hydrogen's GitHub integration.

@kdaviduik
kdaviduik changed the base branch from preview to main October 9, 2026 15:59
@mdamjanic7
mdamjanic7 force-pushed the misha/ucp-discovery-link-tag branch from b895385 to 37219f9 Compare October 14, 2026 21:23
@mdamjanic7 mdamjanic7 self-assigned this Oct 14, 2026
@mdamjanic7
mdamjanic7 force-pushed the misha/ucp-discovery-link-tag branch from 37219f9 to 0c977b6 Compare October 14, 2026 22:26
@mdamjanic7
mdamjanic7 changed the base branch from main to misha/ucp-discovery-link-header October 14, 2026 22:26
@mdamjanic7
mdamjanic7 added this pull request to stack #4187 October 14, 2026 22:26
@mdamjanic7
mdamjanic7 force-pushed the misha/ucp-discovery-link-tag branch 2 times, most recently from 8a80792 to 0a66cd2 Compare October 21, 2026 00:09

@fredericoo fredericoo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

very cool!

zero setup, just works, unsupported browsers ignore the unknown rel type and do not fetch it

PR body says this should ship after #3976 and it has merged so we seem to be ready

@andguy95 andguy95 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Easy change. ✅

@mdamjanic7
mdamjanic7 force-pushed the misha/ucp-discovery-link-tag branch from 0a66cd2 to b230554 Compare October 23, 2026 00:59
@fredericoo
fredericoo force-pushed the misha/ucp-discovery-link-tag branch from b230554 to 0477229 Compare November 12, 2026 11:41
@fredericoo
fredericoo enabled stacked auto-merge November 12, 2026 11:43
@fredericoo
fredericoo added this pull request to the merge queue Nov 12, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to invalid changes in the merge commit Nov 12, 2026
@fredericoo
fredericoo added this pull request to the merge queue Nov 12, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to invalid changes in the merge commit Nov 12, 2026
Base automatically changed from misha/ucp-discovery-link-header to main November 12, 2026 11:47
mdamjanic7 and others added 5 commits November 12, 2026 11:47
Every storefront page now renders <link rel="ucp" href="/.well-known/ucp"> in
its head through getShopifyScriptTags(), so agents and link-preview services
reading the HTML can discover UCP support. The link omits Liquid's version
attribute, matching Oxygen's Link header, so older Hydrogen releases never
advertise a stale profile version.

ShopifyLinkTagAttributes keeps its Partial shape and only gains the "ucp" rel,
so existing consumer code keeps compiling.
The descriptor test already checks the exact UCP link attributes, and the
UCP descriptor assignment in the type tests already covers the rel literal.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants