Route Hydrogen installs through the @subtextdev/hydrogen wrapper - #22
Open
nrodd wants to merge 3 commits into
Open
Route Hydrogen installs through the @subtextdev/hydrogen wrapper#22nrodd wants to merge 3 commits into
nrodd wants to merge 3 commits into
Conversation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Hydrogen apps get the wrapper package instead of a pasted inline snippet: <Subtext> (snippet + CSP nonce), withSubtextCSP in entry.server, <SubtextAnalytics> (commerce events + consent-gated capture + onSessionUrl linkage), and useSubtextIdentity. Detection runs before the Remix/React Router/Vite checks so Hydrogen's own dependencies can't shadow the match, and the pre-check treats @subtextdev/hydrogen as already installed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit ea63429. Configure here.
| 4. `app/entry.server.tsx` — wrap the existing directives object: `createContentSecurityPolicy(withSubtextCSP({...existing directives}))`, importing `withSubtextCSP` from `@subtextdev/hydrogen` (pass `{region: 'eu'}` as its second argument for EU orgs). This replaces the manual CSP directive edits from Step 2 — do not also add the directives by hand. | ||
| 5. `app/root.tsx` — add `<SubtextAnalytics />` anywhere inside `<Analytics.Provider>`. It forwards Hydrogen's commerce events (`product_viewed`, `cart_updated`, search, collection, add/remove-to-cart) into capture and starts/stops capture as Customer Privacy consent changes. | ||
| 6. For Step 5 (identity), use the package's `useSubtextIdentity(customer && {uid: customer.id, displayName, email})` hook where the authenticated customer is available on the client (typically the account route), instead of a raw `FS('setIdentity')` call. | ||
| 7. For Step 6 (analytics linkage), pass `onSessionUrl` to `<SubtextAnalytics>` instead of calling `FS('getSession')` directly — it fires with the session URL every time capture starts, which with consent gating can be well after page load: `<SubtextAnalytics onSessionUrl={(url) => { /* attach subtext_url to each detected tool here */ }} />`. |
There was a problem hiding this comment.
Hydrogen overrides lost in later steps
Medium Severity
Hydrogen-specific identity and analytics guidance appears only as a brief note under Step 4, while Steps 5 and 6 still require raw FS('setIdentity') and FS('getSession') with no Hydrogen exception. Agents following those later steps can skip useSubtextIdentity and onSessionUrl, so consent-gated session URL linkage silently gets nothing.
Additional Locations (2)
Reviewed by Cursor Bugbot for commit ea63429. Configure here.
attachSessionToCart writes the session URL as a _-prefixed cart attribute that Shopify carries onto the order (admin "Additional details"), including the cart-action AttributesUpdateInput case the agent must add and the mode:'ref' fallback for merchants who can't vouch for their notification templates. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
1 participant
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.
What
Teaches
templates/install-prompt.mdthe Shopify Hydrogen route. When the agent detects@shopify/hydrogenin dependencies, it installs the@subtextdev/hydrogenwrapper package instead of pasting the raw inline snippet.Prompt-only change — no wizard code touched, per the "framework logic lives in the agent prompt" architecture.
Changes
@subtextdev/hydrogenin deps now counts as "snippet already installed."orgId/region/host overrides from the org snippet already embedded in the prompt (no invented values), then maps each generic step onto the package surface:<Subtext orgId>inroot.tsx<head>withSubtextCSP(...)inentry.server(replaces the manual directive edits)<SubtextAnalytics />insideAnalytics.ProvideruseSubtextIdentity(customer && {...})onSessionUrlcallback, which fires when capture actually starts (with consent gating that's well after page load, where a rawFS('getSession')call would return nothing)*.oxygenpreview URLs (privacy banner doesn't load), checkout is Shopify-hosted and out of scopeWhy
A Hydrogen install today drops a ~20-line minified snippet into
root.tsxand hand-edits the CSP (see the manual install in the hydrogen-storefront testbed). With the wrapper the diff is a few declarative lines, consent gating matches how Shopify gates its own analytics, and snippet updates ship as package versions instead of re-runs.🤖 Generated with Claude Code
Note
Low Risk
Prompt and documentation only—no wizard runtime code—so behavior changes only affect how the install agent guides Hydrogen projects.
Overview
Hydrogen storefronts are now handled via the
@subtextdev/hydrogenwrapper instead of pasting the raw inline capture snippet.The install prompt treats
@subtextdev/hydrogeninpackage.jsonas already installed, and checks@shopify/hydrogenfirst in framework detection so Remix/Vite deps do not win. A new Shopify Hydrogen framework block maps each install step to the wrapper:<Subtext>+ nonce inroot.tsx,withSubtextCSPinentry.server,<SubtextAnalytics>for commerce events and consent-gated capture,useSubtextIdentityandonSessionUrlfor identity and analytics linkage, plus optionalattachSessionToCart(with cart attribute handling andmode: 'ref'guidance) and user-facing notes on Oxygen preview URLs and checkout scope.README NPM badge colors are updated; a patch changeset documents the wizard release.
Reviewed by Cursor Bugbot for commit 4deab29. Bugbot is set up for automated code reviews on this repo. Configure here.