From 3966b59cd74286bc567d9299d6dd91104fa56cb2 Mon Sep 17 00:00:00 2001 From: Alessandro Casazza Date: Tue, 1 Sep 2026 12:24:40 +0200 Subject: [PATCH] docs(getting-started): add the v4 to v5 upgrade guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers the four changes that actually break a v4 app — the React 19 peer bump, the removal of the 20 subpath exports in favour of a single root entry, `` losing `endpoint` and `domain` now that the organization is derived from the token, and the sibling packages, where a direct dependency on core-components or react-hooks-components shadows the transitive one and leaves two incompatible copies in the tree. Then the full table of the 15 deprecated containers and their standalone replacements, split between straight renames and the ones that dissolve by moving their props onto the children. `` gets its own example, since its props split across two forms. No export was removed from the public API in v5, so the guide leads with the two-stage upgrade: get the app running first, clear the deprecation warnings later. The concept behind the container removal already lives in `005.containers.mdx`, so this page links there rather than restating it, and the same for the core and hooks package pages. Co-Authored-By: Claude Opus 5 (1M context) --- .../getting-started/008.upgrading-from-v4.mdx | 260 ++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 packages/docs/src/stories/getting-started/008.upgrading-from-v4.mdx diff --git a/packages/docs/src/stories/getting-started/008.upgrading-from-v4.mdx b/packages/docs/src/stories/getting-started/008.upgrading-from-v4.mdx new file mode 100644 index 00000000..88c4eb4b --- /dev/null +++ b/packages/docs/src/stories/getting-started/008.upgrading-from-v4.mdx @@ -0,0 +1,260 @@ +import { Meta, Source } from '@storybook/addon-docs/blocks'; + + + +# Upgrading from v4 + +This guide covers the move from `@commercelayer/react-components` **v4** to **v5**. + +Most of the upgrade is mechanical. No component was removed from the public API in v5 — everything exported by v4 is still exported, and the deprecated container components keep working. That means you can upgrade in two stages: get the app running on v5 first, then migrate the deprecated patterns at your own pace. + +There are, however, four changes that **will** break a v4 app and need to be handled up front. Their headings are marked **(breaking)**. + +--- + +## At a glance + +| | v4.29.7 | v5.0.0 | +| --- | --- | --- | +| `react` peer range | `>=18.0.0` | `>=19.0.0` | +| Sibling packages | — | `@commercelayer/core-components`, `@commercelayer/react-hooks-components` | +| Build output | `lib/cjs` + `lib/esm` | `dist` (both CJS and ESM) | +| Subpath exports | 20 (`./orders/*`, `./hooks/*`, …) | none — root entry only | +| `@commercelayer/sdk` | `^6.46.0` | `8.0.0-beta.11` | +| `` props | `accessToken`, `endpoint`, `domain` | `accessToken`, `interceptors` | +| Container components | required | deprecated, standalone components preferred | + +--- + +## 1. Update the dependency + + + +v5 splits the library into three packages. `@commercelayer/core-components` (the framework-agnostic data layer) and `@commercelayer/react-hooks-components` (the SWR-based hooks) are regular dependencies of `@commercelayer/react-components`, so your package manager installs them for you. You do **not** need to add them to your `package.json`. + + +If your `package.json` already lists `@commercelayer/core-components` or `@commercelayer/react-hooks-components` as **direct** dependencies, a direct entry shadows the transitive one: bumping `@commercelayer/react-components` alone will leave the siblings pinned at their old version, and you get two incompatible copies in the same tree. + + +Remove the direct entries and let them resolve through the library: + + + +Only declare them directly if you import from them yourself — and then keep their version in lockstep with `@commercelayer/react-components`. + +--- + +## 2. React 19 (breaking) + +The peer range moved from `>=18.0.0` to `>=19.0.0`. v5 is compiled with the React Compiler targeting React 19, so React 18 is not supported. + + + +The published bundle already carries a `"use client"` banner, so in the Next.js App Router you don't need to add the directive yourself when importing these components. + +--- + +## 3. Deep imports are gone (breaking) + +v4 exposed 20 subpath export patterns, which let you import a single component straight from its file. v5 publishes a **single root entry**, so every import has to come from the package root. + + + +Both CJS and ESM builds are still shipped, so `require()` keeps working at the root entry. Only the subpaths are affected. + +One component changed module while keeping its name: `DeliveryLeadTime` moved from the `skus` folder to `shipping_methods`. If you imported it from the root, nothing changes. + +--- + +## 4. `` loses `endpoint` and `domain` (breaking) + +In v4 you could pass an explicit `endpoint`, or a `domain` the endpoint was built from. Both props are gone. v5 derives the organization from the access token itself, so the token is all the provider needs. + + + {children} + + +// ✅ v5 + + {children} +`} +/> + +If you were passing `domain` to reach a non-default environment, that now belongs to how the token is issued rather than to this component — see Authentication. + +In its place there is a new optional `interceptors` prop, to attach request and response interceptors to the underlying SDK client: + + response, + onFailure: (error) => { throw error } + } + }} +> + {children} +`} +/> + +--- + +## 5. Migrate away from containers + +This is the part you can postpone. Container components still work in v5 — they forward to their replacement and log a deprecation warning in development builds only. They will be removed in the next major version. + +The idea behind the change is described in Containers: components fetch their own data and batch the requests at module level, so the wrapper that existed only to share a fetch is no longer needed. + +### Straight renames + +Same props, shorter name: + +| v4 (deprecated) | v5 | +| --- | --- | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | + + + + + +// ✅ v5 + + +`} +/> + +### Containers that dissolve + +Here the wrapper disappears and its props move onto the components that used to sit inside it. + +| v4 (deprecated) | v5 | +| --- | --- | +| `` | `` standalone, or the `usePrices` hook for batched prices | +| `` | `` standalone — it manages its own context | +| `` | `` standalone | +| `` | `` standalone | +| `` | `` standalone, with `config` passed directly | +| `` | `` and `` directly | +| `` | `` and ``, which take the container's props | + +`` is the one that needs the most care, because its props split across two forms: + + + … + … + + +// ✅ v5 +… +…`} +/> + +And `` simply goes away: + + + + + + +// ✅ v5 + +`} +/> + + +Run your app in development mode after the upgrade and watch the console: every deprecated container you are still using logs a warning naming its replacement. That list is your migration backlog. + + +--- + +## 6. Dependencies you may have relied on indirectly + +v5 drops several transitive dependencies. If your own code imported them without declaring them, add them to your `package.json` explicitly: + +- `lodash` — removed +- `jwt-decode` — removed; token decoding now happens inside `@commercelayer/core-components` +- `iframe-resizer` v4 — replaced by `@iframe-resizer/parent` v5 + +`@commercelayer/sdk` also jumps from `^6.46.0` to `8.0.0-beta.11`. If you use the SDK alongside these components, align your version so the two agree on the resource types. + +--- + +## What's new in v5 + +Beyond the migration, v5 adds surface you may want to adopt: + +- **`@commercelayer/core-components`** — the data layer on its own, usable without React. See Core package. +- **`@commercelayer/react-hooks-components`** — SWR-based hooks with caching, deduplication and loading states. See Hooks package. +- **`useTermsAndConditions`** — reads and updates privacy and terms acceptance, the hook behind ``. +- **New standalone components** — ``, plus the shorter names listed above. +- **`SkuAvailability`** — re-exported as a type from `@commercelayer/core-components`. + +--- + +## Checklist + +1. Bump `@commercelayer/react-components` to v5. +2. Remove any direct dependency on `core-components` or `react-hooks-components`. +3. Move to React 19. +4. Replace deep imports with root imports. +5. Drop `endpoint` and `domain` from ``. +6. Declare any dependency you were getting transitively. +7. Run in development and clear the deprecation warnings when convenient.