fix(examples): run the poc examples with zero setup + stop the dev-server race

[div-cowboy]

TL;DR: This PR was opened before the recent preview refactor, which independently landed most of it (env-var token reads, a mock.shop fallback for the framework examples, per-example dev scripts, and the dev:hub port allocator). It is now rebased onto current preview. What remains is the dev-server race fix, plus extending the mock.shop zero-setup fallback to the five poc/ examples that still throw without a private token.

Before

Two things break a fresh clone of preview:

1. The five examples/poc/* apps throw on every SSR request:

   Error: PRIVATE_STOREFRONT_API_TOKEN is required.
   Run "pnpm run examples:secrets:decrypt" to create local example env files, or set it in the environment.
   

   examples/nextjs and examples/react-router already fall back to mock.shop, but the poc ports still call getPrivateStorefrontToken(), which throws. Anyone outside Shopify cannot decrypt the ejson secrets, so those five apps cannot be run at all.

2. pnpm dev prints a wall of transient errors before settling:

   Module not found: Can't resolve '@shopify/hydrogen'
   

After

1. Every poc example renders against mock.shop with zero setup, with one console warning explaining how to point it at a real store.
2. No module-resolution errors during dev startup.

What this changes

Zero-setup fallback for the poc examples

• New examples/shared/storefront-config.ts. resolveStorefrontConfig(exampleName, env?) returns the configured store when PRIVATE_STOREFRONT_API_TOKEN is present, and otherwise returns mock.shop with its well-known mock-private-token. It warns once per process.
• poc/astro, poc/nuxt, poc/nuxt-binding, poc/solid-start and poc/sveltekit now build their client through it.
• The optional env argument keeps SvelteKit's $env/dynamic/private working, where process.env is not populated.
• mock.shop accepts mock-private-token for the private-client auth header, so the examples keep type: "private". The request-scoped private client contract their handlers and loaders are typed against is unchanged.

Stop the SDK watch from racing the example bundlers

pnpm dev runs both @shopify/hydrogen#build (one-shot, via turbo ^build) and @shopify/hydrogen#dev (tsdown --watch). The watch's default startup clean wipes the just-built dist/ while the example bundlers are reading it through the workspace symlink.

packages/hydrogen/tsdown.config.ts now skips the clean in --watch mode only. Production builds still clean.

Measured locally by sampling dist/ during watch startup: with the current config the file count drops from 563 to 0; with this change it never drops below 563.

Developer impact

No changeset. The only packages/hydrogen change is dev-only build configuration, and production output is unchanged (tsdown already defaults to clean: true, so the non-watch path is identical). Everything else lives under examples/, which .changeset/config.json ignores.

Out of scope

• Customer Accounts on mock.shop. mock.shop has no Customer Account API. The poc account pages already degrade to their signed-out state, so handler registration is left as-is. examples/nextjs and examples/react-router gate theirs; doing the same for the poc ports would mean adding notice UI to five apps.
• Collapsing the framework examples into the shared helper. examples/nextjs and examples/react-router keep their own local resolvers because they also gate Customer Accounts on the same signal.
• Fixed dev-server ports. The original version of this PR pinned a port per example. scripts/examples-dev.ts (pnpm dev:hub) now allocates ports and passes --port, so hardcoding one in each dev script would fight it. Dropped.

Risk

• The poc examples now run against mock.shop silently instead of failing loudly. mock.shop's catalog differs from hydrogen-preview, so pages that depend on store-specific data may render empty rather than erroring. This is the same tradeoff already accepted for examples/nextjs and examples/react-router.

How to Test

Zero-setup fallback (no secrets required)

1. Run pnpm install.
2. Run pnpm --filter @shopify/hydrogen-example-astro dev.
3. Open the printed URL. The home page renders products instead of returning a 500.
4. Confirm the terminal shows one warning: [hydrogen-example-astro] No PRIVATE_STOREFRONT_API_TOKEN found — running against mock.shop (mock.shop).
5. Repeat for @shopify/hydrogen-example-nuxt, -nuxt-binding, -solid-start and -sveltekit.

Dev-server race

1. Run pnpm dev from the repo root.
2. Watch the startup output. There should be no Module not found: Can't resolve '@shopify/hydrogen' lines.

[div-cowboy]

I have signed the CLA!

[div-cowboy]

@jplhomer @frandiox Is this not something wanted for the DX for Hydrogen? Happy to close if not wanted, just trying to start contributing

[fredericoo]

@jplhomer @frandiox Is this not something wanted for the DX for Hydrogen? Happy to close if not wanted, just trying to start contributing

this is something we'd like to have yes! both are great features. will re-open and review now

[div-cowboy]

@fredericoo Awesome. I just rebased and squashed all the conflicts. There was some stuff that was incorporated from other PRs, so I trimmed the fat and updated the PR description.

[div-cowboy]

bump