feat: show a clear error when trying to use CAAPI untunnelled in localhost by fredericoo · Pull Request #3504 · Shopify/hydrogen

fredericoo · 2026-02-25T15:54:05Z

WHY are these changes introduced?

Local development has a bad failure mode for Customer Account OAuth:

When a developer opens /account on localhost without tunneling, the app redirects into the OAuth flow and eventually fails with a redirect URI error from Shopify. The error is late and unclear, so it does not tell developers what they need to do next.

WHAT is this pull request doing?

throws an error and offers a way out for users:
zero impact in bundle size: because NODE_ENV is static at build time, we can get rid of the code path entirely when bundling with vite

HOW to test your changes?

Install deps and build Hydrogen package:
- pnpm --dir packages/hydrogen build
Run unit tests:
- pnpm --dir packages/hydrogen test -- src/customer/customer.test.ts
Start a dev app without customer-account tunneling and visit:
- http://localhost:3000/account
Verify result:
- You should not be redirected to Shopify OAuth.
- You should see a 400 error page with guidance to use --customer-account-push and a *.tryhydrogen.dev URL.
Start dev with tunneling (--customer-account-push) and open the provided *.tryhydrogen.dev URL.
Verify /account continues into normal Customer Account login flow.

Post-merge steps

None.

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 noteworthy changes
I've added tests to cover my changes
I've added or updated the documentation

shopify · 2026-02-25T15:55:52Z

Oxygen deployed a preview of your fb-better-feedback-for-cap branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 3, 202612:48 PM

Learn more about Hydrogen's GitHub integration.

kdaviduik

massive DX improvement ❤️

kdaviduik · 2026-02-26T05:26:07Z

+          throw new Response(
+            [
+              'Customer Account API OAuth requires a Hydrogen tunnel in local development.',
+              'Run `shopify hydrogen dev --customer-account-push`.',


note: these commands can also be aliased as just h2 dev rather than shopify hydrogen dev. i don't think the message needs to be updated but if you can think of a good way to communicate that either one works, go for it

thats very fair

i made it more generic just mentioning to use the flag. if they got to this screen it means they know how to start the dev server, and however they did, they can just add the flag to the end

yep exactly, i think that's super reasonable!

kdaviduik

i trust you, though i'm not able to 🎩 this - i'm seeing this error. both with mock shop and a shop linked. i will investigate more tomorrow - this is also happening to be on main

fredericoo · 2026-02-26T12:43:00Z

i trust you, though i'm not able to 🎩 this - i'm seeing this error. both with mock shop and a shop linked. i will investigate more tomorrow - this is also happening to be on main

yeah this is a real issue: if you are logged in or have a token you get a 500 instead, working on it!

binks-code-reviewer · 2026-02-26T16:10:07Z

🤖 Code Review · #projects-dev-ai for questions
React with 👍/👎 or reply — all feedback helps improve the agent.

✅ Complete - No issues

📋 History

✅ No issues → ✅ No issues → ✅ No issues → ✅ No issues → ✅ No issues

kdaviduik · 2026-02-27T04:29:11Z

+          await customer.login();
+        } catch (error) {
+          const response = error as Response & {message?: string};
+


non-blocking: these tests work correctly because the test file globally stubs Response with a mock class at lines 26-38 that stores the constructor's body argument as .message. This is a pre-existing test pattern, not something this PR introduced.

The tests are correct and pass as intended. However, .message is a non-standard property that only exists due to this mock - the standard Response Web API doesn't have it. If the test environment or mock strategy ever changes, these assertions would silently break. Using await response.text() would be the spec-compliant approach, but since this follows the existing pattern throughout the file, I'm fine with this shipping as-is.

kdaviduik · 2026-02-27T06:13:10Z

+          throw new Response(
+            [
+              'Customer Account API OAuth requires a Hydrogen tunnel in local development.',
+              'Run `shopify hydrogen dev --customer-account-push`.',


yep exactly, i think that's super reasonable!

The development-only tunnel domain check (throwIfNotTunnelled) added in #3504 blocks legitimate HTTPS setups like ngrok and local HTTPS proxies. Rather than loosening the check entirely (which re-introduces the DX gap that #3504 was designed to prevent), this adds an explicit opt-out via the useCustomAuthDomain boolean option. When set to true, the tunnel check logs a warnOnce with actionable guidance (including the redirect_uri to register) instead of throwing. Default behavior is unchanged — developers without the opt-out still get the original error directing them to use --customer-account-push. The implementation uses a closure pattern (ensureTunnel) inside createCustomerAccountClient to avoid pass-through parameters at all 6 call sites. The tunnel check was also extracted from defaultAuthStatusHandler into the authStatusHandler closure for consistent call-site ownership. Fixes #3619

@itsjustriley

…ck (#3642) * feat(hydrogen): add useCustomAuthDomain opt-out for tunnel domain check The development-only tunnel domain check (throwIfNotTunnelled) added in #3504 blocks legitimate HTTPS setups like ngrok and local HTTPS proxies. Rather than loosening the check entirely (which re-introduces the DX gap that #3504 was designed to prevent), this adds an explicit opt-out via the useCustomAuthDomain boolean option. When set to true, the tunnel check logs a warnOnce with actionable guidance (including the redirect_uri to register) instead of throwing. Default behavior is unchanged — developers without the opt-out still get the original error directing them to use --customer-account-push. The implementation uses a closure pattern (ensureTunnel) inside createCustomerAccountClient to avoid pass-through parameters at all 6 call sites. The tunnel check was also extracted from defaultAuthStatusHandler into the authStatusHandler closure for consistent call-site ownership. Fixes #3619 * refactor: rename throwIfNotTunnelled to checkTunnelDomain and flatten nesting The function no longer exclusively throws — when useCustomAuthDomain is enabled, it warns and returns. The new name better describes both code paths. Early returns replace the 3-level-deep nesting with flat, top-to-bottom guard clauses. Addresses review feedback from @itsjustriley. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: add production no-op test for useCustomAuthDomain Verifies that checkTunnelDomain is inert outside of development — the NODE_ENV !== 'development' early return must prevent any warning or throw in production, regardless of the useCustomAuthDomain flag. This guards against accidental removal of the environment gate. Addresses review feedback from @itsjustriley. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: add useCustomAuthDomain coverage for mutate, logout, and authorize Completes tunnel-check test coverage across all six ensureTunnel call sites. Previously only login, query, and handleAuthStatus were tested. This ensures that any method-specific regression in the tunnel check wiring would be caught. Addresses review feedback from @itsjustriley. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: error when using CAAPI untunelled

675d516

fredericoo marked this pull request as ready for review February 25, 2026 16:00

fredericoo requested a review from a team as a code owner February 25, 2026 16:00

kdaviduik approved these changes Feb 26, 2026

View reviewed changes

Comment thread packages/hydrogen/src/customer/customer.ts

Comment thread packages/hydrogen/src/customer/customer.test.ts

Comment thread packages/hydrogen/src/customer/customer.ts Outdated

Comment thread packages/hydrogen/src/customer/customer.ts Outdated

kdaviduik reviewed Feb 26, 2026

View reviewed changes

fredericoo changed the title ~~feat: error when using CAAPI untunelled~~ feat: error when using CAAPI untunnelled Feb 26, 2026

fix: check all caapi endpoints

bb47c9d

fredericoo commented Feb 26, 2026

View reviewed changes

Comment thread packages/hydrogen/src/customer/customer.ts

fredericoo commented Feb 26, 2026

View reviewed changes

Comment thread packages/hydrogen/src/customer/customer.ts Outdated

fredericoo added 5 commits February 26, 2026 17:51

test: verify number of assertions

832eb61

test: verify number of assertions

66587ae

chore: more generic message

569c90f

fix: tunnel check missing

170215b

fix: type for handleAuthStatus

dceae08

fredericoo force-pushed the fb-better-feedback-for-cap branch from a681ba2 to dceae08 Compare February 26, 2026 18:49

fredericoo commented Feb 26, 2026

View reviewed changes

Comment thread packages/hydrogen/src/customer/types.ts Outdated

fredericoo requested a review from kdaviduik February 26, 2026 19:03

kdaviduik reviewed Feb 27, 2026

View reviewed changes

fredericoo changed the title ~~feat: error when using CAAPI untunnelled~~ feat: show a clear error when trying to use CAAPI untunnelled in localhost Feb 27, 2026

fredericoo added 3 commits March 3, 2026 12:36

fix: use plural credentials in CAAPI guidance message

8a71b8a

docs: clarify tryhydrogen tunnel-domain coupling

981a9ee

revert: keep handleAuthStatus type unchanged here

5e0b8a9

fredericoo merged commit 1c19b87 into main Mar 3, 2026
15 checks passed

fredericoo deleted the fb-better-feedback-for-cap branch March 3, 2026 14:53

shopify-github-actions-access Bot mentioned this pull request Mar 3, 2026

[ci] release 2026.1.2 #3524

Merged

chrisvltn mentioned this pull request Mar 16, 2026

fix: allow non-tunnel HTTPS local environments #3592

Closed

5 tasks

vanselowla mentioned this pull request Mar 24, 2026

customerAccount.authorize() blocks non-.tryhydrogen.dev domains in development (e.g. ngrok) #3619

Closed

fredericoo mentioned this pull request Mar 30, 2026

chore: update changelog.json for 2026.1.3 #3636

Merged

fredericoo mentioned this pull request Mar 31, 2026

feat(hydrogen): add useCustomAuthDomain opt-out for tunnel domain check #3642

Merged

4 tasks

Conversation

fredericoo commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

HOW to test your changes?

Post-merge steps

Checklist

Uh oh!

shopify Bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kdaviduik left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdaviduik Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

fredericoo Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

kdaviduik Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

kdaviduik left a comment

Choose a reason for hiding this comment

Uh oh!

fredericoo commented Feb 26, 2026

Uh oh!

binks-code-reviewer Bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kdaviduik Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kdaviduik Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fredericoo commented Feb 25, 2026 •

edited

Loading

shopify Bot commented Feb 25, 2026 •

edited

Loading

kdaviduik left a comment •

edited

Loading

binks-code-reviewer Bot commented Feb 26, 2026 •

edited

Loading