Skip to content

Add UCP discovery Link header to storefront responses - #4153

Merged
fredericoo merged 7 commits into
mainfrom
misha/ucp-discovery-link-header
Nov 12, 2026
Merged

fredericoo merged 7 commits into
mainfrom
misha/ucp-discovery-link-header

Conversation

@mdamjanic7

@mdamjanic7 mdamjanic7 commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

WHY are these changes introduced?

Agents need a way to tell from any storefront URL that the site supports UCP (Universal Commerce Protocol) and where its profile is. Liquid storefronts and Oxygen already send Link: </.well-known/ucp>; rel="ucp" (RFC 8288) on every response. Hydrogen storefronts hosted elsewhere (Vercel, Netlify, Node, and others) don't.

WHAT is this pull request doing?

requestContext.applyResponseHeaders() now adds Link: </.well-known/ucp>; rel="ucp" to every response. Every framework integration already calls it, so no opt-in is needed, and there is no new public API.

  • Every response, regardless of content type or Accept, matching Liquid and Oxygen. An agent's HEAD or curl with Accept: */* discovers UCP from any URL, and no Vary is needed.
  • Appends, never overwrites an existing Link header.
  • No duplicates. Skipped when a rel="ucp" link is already present, so it's idempotent, Oxygen won't add a second one, and an app's own rel="ucp" link takes precedence.
  • No version, so agents get the latest stable profile and old Hydrogen releases never advertise an outdated version.
  • Skipped on *.myshopify.dev. Oxygen deployment URLs don't serve the profile, so the link would 404. Oxygen skips them too.
  • Internal format. The value isn't exported or configurable.

Next.js. Next copies headers set in proxy.ts onto the response before the route runs, then drops any route-handler header with the same name. A UCP Link set in the proxy would therefore replace a route handler's own Link header. No App Router hook runs after the route, so the template's proxy now uses a new lib/proxy-response-headers.ts helper. It applies Hydrogen's headers and then restores Link.

As a result, Next.js pages don't send the UCP header, and advertise UCP through the HTML <link rel="ucp"> tag added in #4154. Responses from handleShopifyRoutes still carry the header. The changeset and the Next.js skill reference describe the pattern.

Docs. The Nuxt skill reference used to copy only Content-Type and cookies back to the response, which would lose this header and the cache headers. It now syncs all headers, like examples/nuxt.

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

HOW to test your changes?

Automated:

  • pnpm --filter @shopify/hydrogen exec vitest run src/core/request-context.test.ts src/core/request-routing
  • pnpm run test:scripts, which includes templates/nextjs/__test__/proxy-response-headers.test.ts
  • pnpm --filter @shopify/hydrogen typecheck, pnpm run lint and pnpm run format:check

Manual:

  1. Run a non-Next example, then curl -sI http://localhost:<port>/. The response includes link: </.well-known/ucp>; rel="ucp".
  2. In templates/nextjs, add a route handler that returns its own Link header. curl -sI shows it unchanged, and /api/cart shows the UCP link.
  3. On Oxygen, the *.myshopify.dev URL has no UCP link, and a custom domain has exactly one.

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

@shopify

shopify Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

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

Storefront Status Preview link Deployment details Last update (UTC)
Skeleton (skeleton.hydrogen.shop) ✅ Successful (Logs) Preview deployment Inspect deployment November 11, 2026 5:55 PM

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-header branch from 3e42ba0 to baa5608 Compare 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-header branch from baa5608 to a996b0e Compare October 20, 2026 23:44

@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.

all good except a test and regex not accounting for a few edge cases

if this was intentional because of oxygen, pls let me know

@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.

Overall looks good 👍 However Freddie's regex concern should be addressed before merge

@mdamjanic7 mdamjanic7 self-assigned this Oct 24, 2026

@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.

LGTM! cheers for parsing the real rel params, and the extra cases (relation lists, quoted params, ; inside the URI) cover it nicely.

E2E is failing on the cart-status contract check, which looks unrelated - probably just needs a rebase with main before merging.

applyResponseHeaders now appends `Link: </.well-known/ucp>; rel="ucp"` to
HTML documents, matching Liquid storefronts and Oxygen. It keeps existing
Link values, skips responses that already carry a rel="ucp" link (using
Oxygen's pattern, so Oxygen does not add a second one), omits version, and
skips *.myshopify.dev Oxygen deployment hosts where the profile does not
resolve.
…links

Drop the HTML/document classification so the header matches Liquid and
Oxygen. The Next.js proxy no longer leaves the UCP Link on
NextResponse.next(), because Next.js lets a proxy header replace a route
handler's header of the same name. Update the Nuxt skill reference to sync
every header, and the changeset to note the dependency on #3976.
Replace the whole-header regex with a small RFC 8288 parser: split link-values
and parameters outside URIs and quoted strings, then match `ucp` in any rel
relation list. Recognizes relation lists and spaced `=`, and no longer
false-positives on quoted non-rel text such as title="; rel=ucp".
@fredericoo
fredericoo force-pushed the misha/ucp-discovery-link-header branch from 9a7a28b to 17c7b2e Compare November 11, 2026 17:50
@fredericoo
fredericoo added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit af55496 Nov 12, 2026
12 checks passed
@fredericoo
fredericoo deleted the misha/ucp-discovery-link-header branch November 12, 2026 11:47
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