Repository navigation
Add UCP discovery Link header to storefront responses - #4153
Merged
Merged
Conversation
5 tasks done
Contributor
|
Oxygen deployed a preview of your
Learn more about Hydrogen's GitHub integration. |
mdamjanic7
force-pushed
the
misha/ucp-discovery-link-header
branch
from
October 14, 2026 22:26
3e42ba0 to
baa5608
Compare
mdamjanic7
force-pushed
the
misha/ucp-discovery-link-header
branch
from
October 20, 2026 23:44
baa5608 to
a996b0e
Compare
fredericoo
reviewed
Oct 21, 2026
fredericoo
left a comment
Contributor
There was a problem hiding this comment.
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
reviewed
Oct 21, 2026
andguy95
left a comment
Collaborator
There was a problem hiding this comment.
Overall looks good 👍 However Freddie's regex concern should be addressed before merge
fredericoo
approved these changes
Nov 11, 2026
fredericoo
left a comment
Contributor
There was a problem hiding this comment.
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
force-pushed
the
misha/ucp-discovery-link-header
branch
from
November 11, 2026 17:50
9a7a28b to
17c7b2e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 addsLink: </.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.Accept, matching Liquid and Oxygen. An agent'sHEADorcurlwithAccept: */*discovers UCP from any URL, and noVaryis needed.Linkheader.rel="ucp"link is already present, so it's idempotent, Oxygen won't add a second one, and an app's ownrel="ucp"link takes precedence.version, so agents get the latest stable profile and old Hydrogen releases never advertise an outdated version.*.myshopify.dev. Oxygen deployment URLs don't serve the profile, so the link would 404. Oxygen skips them too.Next.js. Next copies headers set in
proxy.tsonto the response before the route runs, then drops any route-handler header with the same name. A UCPLinkset in the proxy would therefore replace a route handler's ownLinkheader. No App Router hook runs after the route, so the template's proxy now uses a newlib/proxy-response-headers.tshelper. It applies Hydrogen's headers and then restoresLink.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 fromhandleShopifyRoutesstill carry the header. The changeset and the Next.js skill reference describe the pattern.Docs. The Nuxt skill reference used to copy only
Content-Typeand cookies back to the response, which would lose this header and the cache headers. It now syncs all headers, likeexamples/nuxt.Off Oxygen,
/.well-known/ucpis served byhandleShopifyRoutesonce #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-routingpnpm run test:scripts, which includestemplates/nextjs/__test__/proxy-response-headers.test.tspnpm --filter @shopify/hydrogen typecheck,pnpm run lintandpnpm run format:checkManual:
curl -sI http://localhost:<port>/. The response includeslink: </.well-known/ucp>; rel="ucp".templates/nextjs, add a route handler that returns its ownLinkheader.curl -sIshows it unchanged, and/api/cartshows the UCP link.*.myshopify.devURL has no UCP link, and a custom domain has exactly one.Post-merge steps
Release together with or after #3976.
Checklist