feat!: GraphCommerce 11 — drop Node 20, require Node 22+

.changeset/align-node-supported-versions.md

@@ -0,0 +1,16 @@
+---
+'@graphcommerce/magento-graphcms': major
+'@graphcommerce/magento-open-source': major
+'@graphcommerce/magento-storyblok': major
+'@graphcommerce/hygraph-dynamic-rows-ui': major
+---
+
+**Breaking change — requires Node.js 22 or newer.** This kicks off GraphCommerce 11.
+
+Node.js 20 hit end-of-life in April 2026, so the framework no longer supports it. `engines.node` is now `>=22.0.0 <27.0.0` across the root and all example storefronts — Node 22 (Maintenance LTS) is the new minimum, Node 24 (Active LTS) is recommended, and Node 26 (current) is also accepted.
+
+- CI: `release-canary`, `release-main` and `pr-analysis` now run on Node 24. `periodic-build` matrix changed from `[20, 22]` to `[22, 24]`, and `actions/setup-node` bumped from v3 to v4.
+- `.gitpod.yml` bootstrap moved from `nvm install 18` to `nvm install 24`.
+- Getting-started docs and the three example READMEs now point at Node 22/24.
+
+See [docs/upgrading/graphcommerce-10-to-11.md](docs/upgrading/graphcommerce-10-to-11.md) for the migration steps.

.github/workflows/periodic-build.yml

@@ -21,7 +21,7 @@ jobs:
   publish:
     strategy:
       matrix:
-        version: [20, 22]
+        version: [22, 24]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -31,7 +31,7 @@ jobs:
           path: graphcommerce
 
       - name: Set up Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.version }}
           registry-url: 'https://registry.npmjs.org'

.github/workflows/pr-analysis.yml

@@ -9,7 +9,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: yarn
           cache-dependency-path: package.json
       - run: yarn install

.github/workflows/release-canary.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           cache: yarn
-          node-version: 20
+          node-version: 24
           cache-dependency-path: package.json
           registry-url: 'https://registry.npmjs.org'
           scope: '@graphcommerce'

.github/workflows/release-main.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           cache: yarn
-          node-version: 20
+          node-version: 24
           cache-dependency-path: package.json
           registry-url: 'https://registry.npmjs.org'
           scope: '@graphcommerce'

.gitpod.yml

@@ -1,5 +1,5 @@
 tasks:
-  - before: nvm install 18
+  - before: nvm install 24
     init: |
       cd examples/magento-graphcms
       yarn

docs/getting-started/create.md

@@ -11,7 +11,7 @@ start building.
 ### Preparations
 
 - MacOS, Windows with WSL2 or Linux
-- Install and use node 20: `nvm install 20` or `nvm use 20`
+- Install and use node 22 or 24: `nvm install 24` or `nvm use 24`
 - Install yarn: `corepack enable`
 
 ## Step 1: Create a GraphCommerce app

docs/upgrading/graphcommerce-10-to-11.md

@@ -0,0 +1,94 @@
+# Upgrading from GraphCommerce 10 to 11
+
+GraphCommerce 11 drops support for Node.js 20 (EOL April 2026) and aligns the
+framework with the
+[Node.js release schedule](https://nodejs.org/en/about/previous-releases). The
+minimum supported version is now Node.js 22, and Node.js 24 is recommended.
+
+There are no source-code or API breaking changes in this release — only the
+supported runtime has shifted.
+
+## Step 1: Upgrade your local Node.js
+
+| Version              | Status as of May 2026                                 |
+| -------------------- | ----------------------------------------------------- |
+| Node.js 20 (Iron)    | **EOL** — no longer supported                         |
+| Node.js 22 (Jod)     | Maintenance LTS through ~April 2027 — **new minimum** |
+| Node.js 24 (Krypton) | Active LTS since Oct 2025 — **recommended**           |
+| Node.js 26           | Current since May 2026 — supported                    |
+
+Pick whichever LTS you prefer; `>=22.0.0 <27.0.0` is the accepted range.
+
+With `nvm`:
+
+```bash
+nvm install 24
+nvm use 24
+```
+
+Then re-enable corepack so the project's pinned yarn version is picked up:
+
+```bash
+corepack enable
+```
+
+## Step 2: Bump `engines.node` in your project
+
+If you copied the example's `engines.node` into your own `package.json`, update
+it from the old GC 10 value to the GC 11 range:
+
+```diff
+  "engines": {
+-   "node": ">=20 <24.0.0"
++   "node": ">=22.0.0 <27.0.0"
+  }
+```
+
+If your project doesn't set `engines.node` itself, nothing to do — the engine
+constraint is inherited from `@graphcommerce/magento-graphcms` (or whichever
+example you bootstrapped from).
+
+## Step 3: Update your CI / hosting
+
+Anywhere that pins a Node version, move from 20 to 22 or 24:
+
+- **GitHub Actions** (`.github/workflows/*.yml`):
+
+  ```diff
+  - uses: actions/setup-node@v4
+    with:
+  -   node-version: 20
+  +   node-version: 24
+  ```
+
+  If you use `actions/setup-node@v3`, bump it to `@v4` while you're there.
+
+- **Vercel** — set the project's "Node.js Version" to 22.x or 24.x under
+  Settings → General. Vercel's `20.x` option will be removed in line with Node's
+  own EOL.
+
+- **Docker images** — update any `FROM node:20…` to `FROM node:22-…` or
+  `FROM node:24-…` (alpine/slim/bookworm variants all work).
+
+- **Devcontainer / Gitpod / Codespaces** — Gitpod users can switch their
+  `.gitpod.yml` bootstrap from `nvm install 18` (or 20) to `nvm install 24`.
+  Devcontainer setups that use `"lts": true` resolve to v24 automatically and
+  need no change.
+
+## Step 4: Reinstall
+
+After upgrading Node:
+
+```bash
+rm -rf node_modules .next
+yarn install
+yarn codegen
+yarn dev
+```
+
+## Notes
+
+- Node 22 will move from Maintenance LTS to EOL around April 2027 — start
+  planning the move to Node 24 (or 26) before then.
+- Node 25/26 are non-LTS "current" releases. They're accepted by the engine
+  range, but production deployments should generally stay on the latest LTS.

docs/upgrading/readme.md

@@ -110,6 +110,7 @@ After resolving the diff issues, manually process upgrade instructions:
 - [Upgrading to GraphCommerce 7 to 8](../upgrading/graphcommerce-7-to-8.md)
 - [Upgrading to GraphCommerce 8 to 9](../upgrading/graphcommerce-8-to-9.md)
 - [Upgrading to GraphCommerce 9 to 10](../upgrading/graphcommerce-9-to-10.md)
+- [Upgrading to GraphCommerce 10 to 11](../upgrading/graphcommerce-10-to-11.md)
 
 Run and validate your local environment:
 

examples/magento-graphcms/README.md

@@ -52,7 +52,7 @@ start building.
 
 ### Requirements
 
-- Install and use node 16/18: `nvm install 16` or `nvm use 16`
+- Install and use node 22 or 24: `nvm install 24` or `nvm use 24`
 - Install yarn: `corepack enable`
 
 ## Step 1: Create a GraphCommerce app

examples/magento-graphcms/package.json

@@ -8,7 +8,7 @@
   "packageManager": "yarn@4.5.3",
   "type": "module",
   "engines": {
-    "node": ">=20 <24.0.0"
+    "node": ">=22.0.0 <27.0.0"
   },
   "scripts": {
     "dev": "concurrently -k -n codegen,next 'gc-gql-codegen -w' 'next dev --turbopack' -c 'magenta,cyan'",

examples/magento-open-source/README.md

@@ -33,7 +33,7 @@ start building.
 
 ### Requirements
 
-- Install and use node 16/18: `nvm install 16` or `nvm use 16`
+- Install and use node 22 or 24: `nvm install 24` or `nvm use 24`
 - Install yarn: `corepack enable`
 
 ## Step 1: Create a GraphCommerce app

examples/magento-open-source/package.json

@@ -8,7 +8,7 @@
   "packageManager": "yarn@4.1.1",
   "type": "module",
   "engines": {
-    "node": ">=20 <24.0.0"
+    "node": ">=22.0.0 <27.0.0"
   },
   "scripts": {
     "dev": "concurrently -k -n codegen,next 'gc-gql-codegen -w' 'next dev --turbopack' -c 'magenta,cyan'",

examples/magento-storyblok/README.md

@@ -33,7 +33,7 @@ start building.
 
 ### Requirements
 
-- Install and use node 22/24: `nvm install 22` or `nvm use 22`
+- Install and use node 22 or 24: `nvm install 24` or `nvm use 24`
 - Install yarn: `corepack enable`
 
 ## Step 1: Create a GraphCommerce app

examples/magento-storyblok/package.json

@@ -8,7 +8,7 @@
   "packageManager": "yarn@4.1.1",
   "type": "module",
   "engines": {
-    "node": ">=22 <24.0.0"
+    "node": ">=22.0.0 <27.0.0"
   },
   "scripts": {
     "dev": "concurrently -k -n codegen,next 'gc-gql-codegen -w' 'next dev --turbopack --experimental-https' -c 'magenta,cyan'",

package.json

@@ -14,7 +14,7 @@
     "examples/*"
   ],
   "engines": {
-    "node": ">=20 <24.0.0"
+    "node": ">=22.0.0 <27.0.0"
   },
   "scripts": {
     "prepare": "husky",

packages/hygraph-dynamic-rows-ui/package.json

@@ -16,7 +16,7 @@
     "dev": "next dev"
   },
   "engines": {
-    "node": ">=20 <24.0.0"
+    "node": ">=22.0.0 <27.0.0"
   },
   "dependencies": {
     "@apollo/client": "^4.0.11",