diff --git a/.changeset/align-node-supported-versions.md b/.changeset/align-node-supported-versions.md new file mode 100644 index 0000000000..c05ebe18dd --- /dev/null +++ b/.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. diff --git a/.github/workflows/periodic-build.yml b/.github/workflows/periodic-build.yml index 0bd36f1808..0800e4c589 100644 --- a/.github/workflows/periodic-build.yml +++ b/.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' diff --git a/.github/workflows/pr-analysis.yml b/.github/workflows/pr-analysis.yml index 466719af48..0cf0a66cec 100644 --- a/.github/workflows/pr-analysis.yml +++ b/.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 diff --git a/.github/workflows/release-canary.yml b/.github/workflows/release-canary.yml index 14e5279682..bb500a8098 100644 --- a/.github/workflows/release-canary.yml +++ b/.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' diff --git a/.github/workflows/release-main.yml b/.github/workflows/release-main.yml index 35c2242faf..df16945831 100644 --- a/.github/workflows/release-main.yml +++ b/.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' diff --git a/.gitpod.yml b/.gitpod.yml index 381dc78000..4c50ad0bd0 100644 --- a/.gitpod.yml +++ b/.gitpod.yml @@ -1,5 +1,5 @@ tasks: - - before: nvm install 18 + - before: nvm install 24 init: | cd examples/magento-graphcms yarn diff --git a/docs/getting-started/create.md b/docs/getting-started/create.md index e8e24227fb..db1daf209d 100644 --- a/docs/getting-started/create.md +++ b/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 diff --git a/docs/upgrading/graphcommerce-10-to-11.md b/docs/upgrading/graphcommerce-10-to-11.md new file mode 100644 index 0000000000..55b7348e14 --- /dev/null +++ b/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. diff --git a/docs/upgrading/readme.md b/docs/upgrading/readme.md index d363c1c2ab..480e77596c 100644 --- a/docs/upgrading/readme.md +++ b/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: diff --git a/examples/magento-graphcms/README.md b/examples/magento-graphcms/README.md index 865df4e6df..9c0f31407d 100644 --- a/examples/magento-graphcms/README.md +++ b/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 diff --git a/examples/magento-graphcms/package.json b/examples/magento-graphcms/package.json index f1c9011d4c..21c1432788 100644 --- a/examples/magento-graphcms/package.json +++ b/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'", diff --git a/examples/magento-open-source/README.md b/examples/magento-open-source/README.md index b58bd941f6..4098d239d2 100644 --- a/examples/magento-open-source/README.md +++ b/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 diff --git a/examples/magento-open-source/package.json b/examples/magento-open-source/package.json index db6c4d5024..7128c74dc0 100644 --- a/examples/magento-open-source/package.json +++ b/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'", diff --git a/examples/magento-storyblok/README.md b/examples/magento-storyblok/README.md index 019f756a91..5e1b1fd0fe 100644 --- a/examples/magento-storyblok/README.md +++ b/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 diff --git a/examples/magento-storyblok/package.json b/examples/magento-storyblok/package.json index 79fa591141..95618de452 100644 --- a/examples/magento-storyblok/package.json +++ b/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'", diff --git a/package.json b/package.json index 6f6dbeb1cf..dbf20d6f66 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "examples/*" ], "engines": { - "node": ">=20 <24.0.0" + "node": ">=22.0.0 <27.0.0" }, "scripts": { "prepare": "husky", diff --git a/packages/hygraph-dynamic-rows-ui/package.json b/packages/hygraph-dynamic-rows-ui/package.json index 76bc2da50e..d02bae0e7c 100644 --- a/packages/hygraph-dynamic-rows-ui/package.json +++ b/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",