feat(hydrogen): support React Router 8

.changeset/react-router-8-support.md

@@ -0,0 +1,14 @@
+---
+'@shopify/hydrogen': major
+'@shopify/cli-hydrogen': major
+'@shopify/remix-oxygen': major
+'skeleton': major
+'@shopify/create-hydrogen': patch
+'@shopify/hydrogen-react': patch
+---
+
+Support React Router 8 in Hydrogen.
+
+New Hydrogen projects now use React Router 8, React 19.2.7, and Node 22.22.0 or newer. The Hydrogen preset emits React Router 8-compatible configuration, the scaffold no longer installs `react-router-dom`, route `meta` exports use `loaderData` instead of the removed `data` parameter, and package scripts call the local Hydrogen CLI package directly so the scaffolded CLI behavior matches the installed Hydrogen version.
+
+Hydrogen and `@shopify/remix-oxygen` now publish ESM entrypoints only because React Router 8 is ESM-only. If your app still depends on CommonJS `require()` entrypoints for these packages, migrate those imports to ESM before upgrading.

.claude/commands/changelog-update.md

@@ -286,7 +286,7 @@ For packages that need to be removed during migration (like Remix → React Rout
 #### Framework Package Types (include only if changed in skeleton)
 
 - `@shopify/hydrogen` (usually changes with every major release)
-- React Router packages (`react-router`, `react-router-dom`, `@react-router/*`)
+- React Router packages (`react-router`, `@react-router/*`)
 - `@shopify/cli` (when CLI is updated)
 - `@shopify/mini-oxygen` (when dev server is updated)
 - `@shopify/hydrogen-codegen`, `@shopify/oxygen-workers-types`
@@ -298,6 +298,8 @@ For packages that need to be removed during migration (like Remix → React Rout
 - Most eslint, typescript, prettier packages - User tooling preferences
 - Application-specific dependencies
 
+**Exception**: Include `react`, `react-dom`, and React type packages when a framework dependency raises its minimum React baseline. For example, React Router 8 requires React 19.2.7+, so the changelog entry for that migration must update React packages or merchant upgrades can leave an unsupported React 18 install behind.
+
 #### Comprehensive Dependency Analysis Example
 
 ```bash
@@ -309,23 +311,25 @@ git diff PREVIOUS_RELEASE_HASH:templates/skeleton/package.json CURRENT_RELEASE_H
 
 # Step 3: Analyze the diff output
 Example diff showing:
-+ "@shopify/cli": "~3.80.4"           # CLI version bump - INCLUDE
-- "@shopify/cli": "~3.79.2"
-+ "react-router": "7.6.0"             # New React Router - INCLUDE
-+ "react-router-dom": "7.6.0"         # New React Router DOM - INCLUDE
++ "@shopify/cli": "~3.94.0"           # CLI version bump - INCLUDE
+- "@shopify/cli": "~3.93.2"
++ "react-router": "8.0.1"             # React Router baseline - INCLUDE
++ "react": "19.2.7"                   # Required by framework baseline - INCLUDE
++ "react-dom": "19.2.7"               # Required by framework baseline - INCLUDE
+- "react-router-dom": "7.16.0"        # Removed by React Router 8 - REMOVE
 - "@remix-run/react": "^2.16.1"       # Removed Remix - REMOVE from changelog
 - "@remix-run/server-runtime": "^2.16.1" # Removed Remix - REMOVE from changelog
-  "react": "^18.2.0"                  # Unchanged - EXCLUDE (user dependency)
   "graphql": "^16.10.0"               # Unchanged - EXCLUDE (user dependency)
 
 # Step 4: Final inclusion decision
 INCLUDE in changelog:
-- "@shopify/cli": "~3.80.4"           # Framework tool, version changed
-- "react-router": "7.6.0"             # Framework package, newly added
-- "react-router-dom": "7.6.0"         # Framework package, newly added
+- "@shopify/cli": "~3.94.0"           # Framework tool, version changed
+- "react-router": "8.0.1"             # Framework package, version changed
+- "react", "react-dom"                # Required by framework baseline
+- "react-router-dom"                  # Remove (no longer published for React Router 8)
 
 EXCLUDE from changelog:
-- "react", "graphql", etc.             # User application dependencies
+- "graphql", etc.                      # User application dependencies
 - "@remix-run/react"                   # Remove (no longer in skeleton)
 ```
 
@@ -445,8 +449,10 @@ git diff PREV:templates/skeleton/package.json CURR:templates/skeleton/package.js
 // CORRECT - Only changed framework dependencies
 {
   "dependencies": {
-    "@shopify/hydrogen": "2025.5.0",    // Framework - changed
-    "react-router": "7.6.0"             // Framework - newly added
+    "@shopify/hydrogen": "2026.5.0",    // Framework - changed
+    "react-router": "8.0.1",            // Framework - changed
+    "react": "19.2.7",                  // Required by React Router 8
+    "react-dom": "19.2.7"               // Required by React Router 8
   }
 }
 ```
@@ -627,4 +633,4 @@ Please confirm: Should I proceed with updating the changelog? (y/n)
 - **Acknowledge**: "Understood. The changelog entry has been generated but not added to the file."
 - **Preserve**: "You can copy the generated JSON entry if you want to add it manually later."
 
-**IMPORTANT**: Only modify the changelog.json file if the user explicitly confirms. Never assume or proceed without clear permission.
+**IMPORTANT**: Only modify the changelog.json file if the user explicitly confirms. Never assume or proceed without clear permission.

.docs/dependencies.md

@@ -0,0 +1,26 @@
+# Documentation Dependencies
+
+Quick lookup: "I changed X, what docs do I update?"
+
+## React Router Baseline
+
+**Code**:
+- `package.json`
+- `pnpm-workspace.yaml`
+- `packages/hydrogen/src/react-router-preset.ts`
+- `packages/cli/package.json`
+- `packages/cli/bin/shopify-hydrogen.js`
+- `packages/cli/src/bin.ts`
+- `packages/cli/src/commands/hydrogen/upgrade.ts`
+- `templates/skeleton/package.json`
+- `templates/skeleton/README.md`
+- `templates/skeleton/react-router.config.ts`
+- `docs/preview/package.json`
+
+**Docs to Update**:
+- `templates/skeleton/.cursor/rules/hydrogen-react-router.mdc` - import guidance for generated projects
+- `templates/TEMPLATE_GUIDELINES.md` - route API terminology
+- `packages/hydrogen/react-router.d.ts` - React Router augmentation comments
+- `.claude/commands/changelog-update.md` - release changelog dependency rules
+- `cookbook/recipes/*/README.md` and `cookbook/llms/*.prompt.md` - generated recipe examples after route or dependency baseline changes
+- `docs/changelog.json` - release metadata when the release PR is generated

.github/workflows/ci.yml

@@ -323,14 +323,42 @@ jobs:
             --path "${{ runner.temp }}/h2-test-${{ matrix.pm }}" \
             --language ts \
             --mock-shop \
-            --install-deps \
+            --no-install-deps \
             --no-git \
             --package-manager ${{ matrix.pm }} \
             --no-shortcut \
             --markets none \
             --styling none
         shell: bash
 
+      - name: 📦 Install with local Hydrogen packages
+        run: |
+          package_dir="${{ runner.temp }}/h2-local-packages"
+          mkdir -p "$package_dir"
+
+          pack_package() {
+            npm_config_ignore_scripts=true pnpm --dir "$1" pack --pack-destination "$package_dir" --json | node -e "let input = ''; process.stdin.on('data', (chunk) => input += chunk); process.stdin.on('end', () => { const result = JSON.parse(input); console.log((Array.isArray(result) ? result[0] : result).filename); });"
+          }
+
+          hydrogen_react_tarball="$(pack_package packages/hydrogen-react)"
+          hydrogen_tarball="$(pack_package packages/hydrogen)"
+          cli_tarball="$(pack_package packages/cli)"
+
+          cd "${{ runner.temp }}/h2-test-${{ matrix.pm }}"
+
+          case "${{ matrix.pm }}" in
+            npm)
+              npm install "$hydrogen_react_tarball" "$hydrogen_tarball" "$cli_tarball"
+              ;;
+            pnpm)
+              pnpm add "$hydrogen_react_tarball" "$hydrogen_tarball" "$cli_tarball"
+              ;;
+            yarn)
+              yarn add "$hydrogen_react_tarball" "$hydrogen_tarball" "$cli_tarball"
+              ;;
+          esac
+        shell: bash
+
       - name: ✅ Verify lockfile
         run: |
           if [ ! -f "${{ runner.temp }}/h2-test-${{ matrix.pm }}/${{ matrix.lockfile }}" ]; then
@@ -386,7 +414,7 @@ jobs:
       - name: 🚀 Deploy skeleton to Oxygen
         id: deploy
         working-directory: templates/skeleton
-        run: pnpm exec shopify hydrogen deploy --no-lockfile-check --force --auth-bypass-token --env-file ../../e2e/envs/.env.customerAccount
+        run: pnpm exec shopify-hydrogen deploy --no-lockfile-check --force --auth-bypass-token --env-file ../../e2e/envs/.env.customerAccount
         env:
           SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_1000108386 }}
 

.github/workflows/deploy-examples.yml

@@ -93,7 +93,7 @@ jobs:
         id: deploy
         working-directory: templates/skeleton
         run: |
-          pnpm exec shopify hydrogen deploy --force --no-lockfile-check --token=$OXYGEN_DEPLOYMENT_TOKEN_${{ matrix.recipes.token }}
+          pnpm exec shopify-hydrogen deploy --force --no-lockfile-check --token=$OXYGEN_DEPLOYMENT_TOKEN_${{ matrix.recipes.token }}
         env:
           SHOPIFY_HYDROGEN_FLAG_METADATA_DESCRIPTION: 'Recipe: ${{ matrix.recipes.name }} - ${{ github.event.head_commit.message }}'
           OXYGEN_DEPLOYMENT_TOKEN_1000014888: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_1000014888 }}

.github/workflows/deploy.yml

@@ -44,6 +44,6 @@ jobs:
       - name: Build and Publish to Oxygen
         id: deploy
         working-directory: templates/skeleton
-        run: pnpm exec shopify hydrogen deploy --no-lockfile-check
+        run: pnpm exec shopify-hydrogen deploy --no-lockfile-check
         env:
           SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_1000014875 }}