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.