docs(getting-started): add the v4 to v5 upgrade guide - #826
Merged
Conversation
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, `<CommerceLayer>` 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. `<AddressesContainer>` 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) <noreply@anthropic.com>
✅ Deploy Preview for commercelayer-react-components ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
packages/docs/src/stories/getting-started/008.upgrading-from-v4.mdx, a Storybook page walking through the move from v4 to v5. It shows up eighth under Getting Started, after Hooks package.What it covers
The page leads with the fact that no export was removed from the public API in v5, so the upgrade can be done in two stages: get the app running on v5 first, clear the deprecation warnings later.
Then the four changes that genuinely break a v4 app:
>=18.0.0→>=19.0.0; compiled with the React Compiler targeting 19<CommerceLayer>endpointanddomainremoved — the organization is derived from the token; new optionalinterceptorscore-components/react-hooks-componentsshadows the transitive one and leaves two incompatible copies in the treeFollowed by the full table of the 15 deprecated containers and their standalone replacements, split between straight renames (
<OrderContainer>→<Order>) and the ones that dissolve by moving their props onto the children.<AddressesContainer>and<PlaceOrderContainer>get their own before/after examples.What it deliberately does not do
The concept behind dropping containers is already in
005.containers.mdx, and the two new packages are documented in006.core.mdxand007.hooks.mdx. This page links to all three instead of restating them — it contributes the complete migration table, which none of them has.Verification
pnpm build && pnpm docs:buildboth pass, which is the Netlify pathindex.json/index.json, not guessed<Source>blocks and both callouts render correctlyOne fix during authoring worth noting:
<span type="warning">is styled as a full-width block callout by the theme, so it cannot be used inline — it was splitting a sentence around an orange box. Inline markers are plain(breaking)text now, and the two remaining<span>blocks are standalone.Content sourced from
git diff v4.29.7..main, the deprecation JSDoc on each container, andtsdown.config.tsfor the build formats. Every claim in the table was read off the code rather than recalled — including that both CJS and ESM are still shipped, so v5 is not ESM-only.