A Sort of Guide to Migrating to @backpackjs/storefront v2 + Cart API

The following is guide for migrating a project currently using @backpackjs/storefront v1 to use @backpackjs/storefront v2 with the new Cart API. It's loosely based off of seven commits made by Nguyen, each addressing a different part of the migration. If you follow along and do the same things that he did in these seven commits, you should be somewhere between 80 - 90% done with the migration. The remaining work will/ be project specific and I'm not sure there's much I can do for you there.

The 7 Commits (👈🏻 this links to the pull request)

1. feat: initial scaffold for migrating LIV to latest (👈🏻 these link to the headings in this document)
2. chore: replace singular inits with useStorefrontInit in layout
3. fix: the cart selects in local store
4. feat: fix up the cart line items and some elevar stuff
5. feat: fix up account page
6. fix: add checks in for elevar orders [1]
7. fix: add checks in for elevar orders [2]

1. feat: initial scaffold for migrating LIV to latest (👈🏻 this links to the commit)

   Objectives

   • [ ] Update dependencies in package.json^1 (👈🏻 and these link to examples of whatever was just talked about)
   • [ ] Migrate all imports using '@backpackjs/storefront'; to '@backpackjs/storefront/v2';
   • [ ] Eliminate all instances of @backpackjs/utilities being imported into the project and replace with the equivalent functionality ^2

   Gotchas

   • Problem: You may need to add components that aren't in the project and are no longer available in newer versions of @backpackjs/storefront

     Solution: First check all your projects and see if you can find a version of the component you need. If you can't find it anywhere there, you'll have to go and look at an old commit from a point in time when the monorepo had what you're looking for.

     For example, say you need the ShopifyMedia component but you can't find it anywhere. You suspect that it was in the storefront package back in January, so you find a commit from January, then you find and click on the button that says "Browse Files" and then you search for the component, utility, whatever you're looking for.

   • Problem: Occurances of @backpackjs/utilities are infrequent and can difficult to anticipate and identify

     Solution: The easiest way to resolve this quickly is to do a find all in folder search for @backpackjs/utilities and just pick them off one by one. You may have to move the actual utility function into the project somewhere. Use this change as an example.

2. chore: replace singular inits with useStorefrontInit in layout

   Objectives

   • [ ] Add what is now the now only init to layouts/Storefront.jsx^3
   • [ ] Remove all instances of useCartInit and useCustomerInit^4

   Gotchas

   • none

3. fix: the cart selects in local store

   Objectives

   • [ ] Update the data passed to cartAddItem and it's derivatives
     • [ ] variantId becomes merchandiseId ^6
     • [ ] customAttributes becomes attributes [^7]
   • [ ] Update the data passed to cartUpdateItem and it's derivatives
     • [ ] id becomes lineId
   • [ ] Either the data structure for the cart changed or one of the values in the cart changed type (e.g. string to Base64 encoded) and as a result we have to do a little more legwork to find matches in the cart[^8]
   • [ ] Additionally, the nomenclature has changed between the buy sdk and the new Cart API. What was once known as lineItems is now simply known as lines[^9][^10]

   Gotchas

   • Problem: The changes in data structure and wording can be pretty subtle and difficult to spot at times

     Solution: Be aware that wherever this type of data shows up is usually preceeded by fetching some data from the recoil store e.g. get(store.state.cartItems$). Because your project might be different enough that you couldn't just copy liquid-iv, you might need to do a little sleuthing in order to find all the places that need to be updated. First, I would think of all the places where cart data is used and poke around there for and updates. And then second, I would do a search all for "get(store.state." and look around there, and by that point you should have found everything.

4. feat: fix up the cart line items and some elevar stuff

   Objectives

   • [ ] Add some optional chaining inside elevar data to avoid throwing errors[^11][^12]
   • [ ] Account for changes in data structure inside cart variant prices[^13]

   Gotchas

   • none

5. feat: fix up account page

   Objectives

   • [ ] Note the change in data returned from useCustomerAddresses and update accordingly[^14]
   • [ ] Remove any imports leveraging the dynamic import[^15]
   • [ ] Remove redirect logic for customers with accounts but no order history[^16]

   Gotchas

   • Problem: Note how optional chaining is added in varoius places throughout. You might think that you don't have to bother with making those little changes because they won't actually make any difference and so you don't. Then 45 minutes passes and an unexplained error pops up all of a sudden. Then three days pass and, oop, another unexplained error. A week goes by, a month, and the whole time all these seemingly random cannot read property of undefined errors keep popping up.

     Solution: Those optional chainging updates were/are probably in there for some reason. Save yourself the headache and just add them now instead of periodically over the next four months.

6. fix: add checks in for elevar orders [1]

   Objectives

   • [ ] More optional chaining[^17][^18][^19][^20]

   Gotchas

   • none

7. fix: add checks in for elevar orders [2]

   Objectives

   • [ ] Even?.more?.optional?.chaining[^21][^22][^23][^24][^25][^26][^27][^28]

   Gotchas

   • none

[^7]: That update got missed in this commit but now is the best time to make that change [^8]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/142c6993605a996d232bba9c56492a52d1034250#diff-eb4bbe1862b0947ee19c8404f5082875e9a71dcbb00c40e95380fd30c6eb280fL16-R22 [^9]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/142c6993605a996d232bba9c56492a52d1034250#diff-eb4bbe1862b0947ee19c8404f5082875e9a71dcbb00c40e95380fd30c6eb280fL56-R68 [^10]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/142c6993605a996d232bba9c56492a52d1034250#diff-0d5d478b2c8a08b0341a01205ffc8278c8a99c42c9f2f95022822690bf983452L12-R21 [^11]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5127f3b292369fdca16de4b1898a63d68144f99b#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daL57-R57 [^12]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5127f3b292369fdca16de4b1898a63d68144f99b#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daL250-R250 [^13]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5127f3b292369fdca16de4b1898a63d68144f99b#diff-eb4bbe1862b0947ee19c8404f5082875e9a71dcbb00c40e95380fd30c6eb280fL27-R29 [^14]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/45007baecaf5f41494e232daecbc6abae233a237#diff-569e2983db359d17fcb5d29dae2502d67704357900093040b542a7876cdb33edL15-R14 [^15]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/45007baecaf5f41494e232daecbc6abae233a237#diff-34aabcf864b094b1b025481f38b394cff794b318a4f8f3b32fd2cfeb2b956bfeL10-R10 [^16]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/45007baecaf5f41494e232daecbc6abae233a237#diff-34aabcf864b094b1b025481f38b394cff794b318a4f8f3b32fd2cfeb2b956bfeL71-L81 [^17]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5cbbc4f4a36bd1749bbcc25470403763600ce566#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR31 [^18]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5cbbc4f4a36bd1749bbcc25470403763600ce566#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR62 [^19]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5cbbc4f4a36bd1749bbcc25470403763600ce566#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR89 [^20]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/commit/5cbbc4f4a36bd1749bbcc25470403763600ce566#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR111 [^21]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR60 [^22]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR61 [^23]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR64 [^24]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR87 [^25]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR88 [^26]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR89 [^27]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR109 [^28]: https://github.com/packdigital/liquid-i-v-storefront-bdn7x/pull/247/commits/875a46467ccc6b5c6c591ef51423046f6c0b003d#diff-c58dda54d8c1263bc712de920cb26f1a686396d615e0daba8f1c53bcce5412daR110