React Components / Hooks for easy interaction with Medusa API

[srindom]

Hey everyone! :)

We are looking to add a package that provides a handful of simple React Hooks that can be used to easily interact with the Medusa API to create cool storefront experiences. Before we begin working on this we would like to get some input on how the hooks should work.

We have discussed the following:

Add a MedusaProvider around the root of your React app.

<MedusaProvider baseUrl={...}>
  <App />
</MedusaProvider>

Medusa Provider allow you to use the following hooks:

• useProducts()
• useCart()
• useShippingOptions()
• useCollections()
• ...

We would like some input on the proper return types for our hooks. The goal is for them to be as easy to work with when building React storefronts for Medusa three approaches we have discussed are:

Cart with functions

const cart = useCart()

console.log(cart.email) // [email protected]
cart.addLineItem({ variantId: ..., quantity: ... }) // calls POST /carts/:id/items

Cart and functions separated

const { cart, actions } = useCart()

console.log(cart.email) // [email protected]
actions.addLineItem({ variantId: ..., quantity: ... }) // calls POST /carts/:id/items

Cart and functions separated + spread into return

const { cart, addLineItem } = useCart()

console.log(cart.email) // [email protected]
addLineItem({ variantId: ..., quantity: ... }) // calls POST /carts/:id/items

The Hook/Component library would be typed so that your IDE can help you explore the API.

Would be great to hear what you guys think?

[pKorsholm]

In terms of which to choose I personally think that options 1 and 3 are the best from a design perspective.

• Option 1
  is what one would do in a Domain Driven Design scenario, and i think it makes sense from that perspective, it's very classically object oriented and there are a lot of examples of this working very well
• Option 2
  I think this might cause more confusion than it does good with client code becoming littered with action objects, which can seem ambiguous if you are not aware about the specific context in which it is used. I'm aware that you can name these objects, but I would rather pick a solution that is "failsafe default", to borrow a security term
• Option 3
  I see definite similarities between this and the first one. This one seems more expressive and is clearly indicating what functionality is used in the code following. I personally enjoy this syntax more since it makes identifying which API calls the code will make easier, rather than having to look through the code for every instance of the cart which would be the case for Option 1. There is of course the obvious antipattern here to simply to const {cart, ...rest } = useCart() at which point we have arrived at Option 2

[zakariaelas]

This comment will try to summarize the team's findings and decisions in regards to building a Medusa React Hooks library

Motivation

In a continuous effort to improve the developer experience (DX) at Medusa, we want to build a React Hooks library for our users who use React. Also, because we use React quite a lot internally, we want to use this internally as well.

Decisions

We came across react-query and saw it as a great candidate for solving most of our pains when interacting with the Medusa API. It solves a large subset of the problems we are already facing (caching, deduping requests, optimistic updates, background re-fetching, etc.), so we decided to build on top of react query. The library advocates for the separation of server state and client state which leads to a much cleaner and extensible codebase. We like this approach and decided to keep it mind while developing our hooks library. This implies that we should definitely NOT shy away from having more than 1 or 2 contexts if we think it'll lead to a more powerful library/API (see CartContext next for an example).

First Implementation

You can refer to this fork for a first (naive) implementation of the above decisions. To elaborate on the separation of client and server state a little bit further, we can use the CartContext as an example. The context is responsible for managing the cart state across the entire application. I believe this state falls into the client state because at no time do we interact with a server while managing this state. Of course, eventually, we'll need to create a cart, but I think this should be handled through a useCreateCart hook, which will wrap over react query's useMutation, whereas the useCart hook will take care of operations such as: adding an item, removing an item, updating an item, computing the cart total, etc.

One other thing to note is that the hooks written so far are not enough to cover the entire starter, so only the / and /products/[id] pages are using the "draft" medusa-hooks library. The src/components/layout/nav-bar.jsx and src/components/cart-view/cart-view.jsx components were also slightly modified to use our useCart hook.

We are also still in the process of defining an interface, but to build on the discussion above, I believe that we're heading towards Option 3 for most of our hooks. Although, for the useItem hook we have so far, a helpers property which resembles the actions property above is returned from the hook. Only reason why I went with that is because I don't want to force long object destructures and instead leave it to the user to either destructure in a subsequent line of code, or use the helpers object like such: helpers.decrementQuantity . The useItem is by no means something we HAVE to use because it's really only there to provide some help with the most common operations when seeing a product page (incrementing and decrementing quantity, and selecting a variant). However, I'm only bringing it up here to say that we MIGHT run into scenarios where it might be fair to consider Option 2.

Finally, please feel free to clone the fork and play around with it. Would be awesome to have everyone share their thoughts and concerns early on so we can consider those before starting the implementation (although we all agree that this will be an iterative process).

[zakariaelas]

Progress Update

Hello everyone, wanted to give an update on the progress made so far as well as get your feedback on the work so far. You can find the repo here.

I used a tool called tsdx which was made to make creating libraries easier as far as the tooling goes. It was quite helpful to use to quickly start a typescript project. So dropping it here for future usage (perhaps the medusa-js lib could use it too)

Before you clone the repo, please note:

To make medusa-hooks compile and work correctly, I had to make some changes to the medusa-js client. You can find my branch under medusa-js/fix/medusa-hooks , once you pull the branch, run yarn link inside the root of the project, then run yarn link again once in the medusa-hooks project.

Experimenting and playing around with the lib

I'm still experimenting with ways to quickly demo the hooks. For now, medusa-hooks uses storybook to provide a testing playground. Each story consumes a particular hook and exposes some controls you can tweak to test out the hook. You'll also get JSON data on the right panel of every story to clearly see what each hook returns. Just remember to run yarn storybook.

I'll keep adding stories for each hook we make, however, would love to hear if you guys have a quick and efficient way of providing a playground-like experience for team members to play around with the hooks. Eventually, we will test every hook on the library, however, in my head, what i'm talking about should come a bit before because I still consider the APIs and types to change based on the team's feedback. So what i'm trying to figure out is a way to help you build such a feedback without having to waste too much of your time setting up different projects, linking dependencies, etc.

Let me know what you guys think!