RFC: Hydrogen Cart

[lordofthecactus]

A proposal for a Hydrogen cart abstraction optimized for Remix.

Background

Hydrogen v2 in Remix does not currently provide an easy path for setting up a Cart:

• Current cart setup documentation is four pages long.
• A lot of manual work is required that even some users prefer to use hydrogen-react's component CartProvider. This component works fully client side, but it is not optimized for Remix and server rendering.

We think that providing a Remix optimized Cart abstraction should make it a lot easier to setup a cart and improve performance.

Proposal

Setup

1. Add createCartApi to the Remix context in server.ts:

import {createCartApi} from '@shopify/hydrogen';

...
+ const cart = createCartApi({
+  storefront,
+  request,
+ });

const handleRequest = createRequestHandler({
  build: remixBuild,
  mode: process.env.NODE_ENV,
+ getLoadContext: () => ({session, storefront, cart, env}),
});

if you are using TypeScript, make sure to add your CartApiReturn type to `remix.env.d.ts:

+ import {type CartApiReturn} from '@shopify/hydrogen';

declare module '@shopify/remix-oxygen' {
 export interface AppLoadContext {
   session: HydrogenSession;
   storefront: Storefront;
+  cart: CartApiReturn;
   env: Env;
 }
}

2. Add CartForm to your UI. For example on a product page:

import {CartFormInputAction} from '@shopify/hydrogen';
import {CartForm} from '~/components/CartForm'; // temporary

export async function loader() {
  ...
  return json({product})
}

export default function Product() {
  const {product} = useLoaderData<typeof loader>();
  const firstVariant = product.variants.nodes[0];
  const selectedVariant = product.selectedVariant ?? firstVariant;

+ const formInputs = {
+  action: CartFormInputAction.CartLinesAdd,
+  lines: [{
+    merchandiseId: variant.id,
+    quantity: 1
+  }]
 };

  // Note: I didn't define a route prop for CartForm
  // this means that this form will submit to this route
  return (
   <>
     <h2>{title} - {vendor}</h2>
+    <CartForm formInput={formInputs}>
+      {(fetcher) => (
+        <button disabled={fetcher.state !== 'idle'}>
+          Add to cart
+        </button>
+      )}
+     </CartForm>
    </>
  )
};

3. Add an action to handle the cart form:

export async function loader() {
  ...
}

export async function action({request, context}: ActionArgs) {
 const {cart} = context;
 const headers = new Headers();

 const formData = await request.formData();
+const cartInput = cart.getFormInput(formData);

 let status = 200;
+const result = await cart.addLine(cartInput);

+cart.setCartId(result.cart.id, headers);

 return json(
   result,
   {status, headers},
 );
}

export default function Product() {
 ...
}

Advanced (optional) - Customize cart queries and logic

Sometimes, what we have as default isn’t what you need. You can completely customize your cart api however you want it.

1. Copy createCartApi into your project

Put the following code into your project in a file call /app/lib/cart-queries.server.ts:

import {getFormInput} from '~/components/CartForm'; // temporary
import type {
 CartQueryOptions,
 CartQueryReturn,
 CartBuyerIdentityUpdate,
 CartCreate,
 CartDiscountCodesUpdate,
 CartFormInput,
 CartLinesAdd,
 CartLinesRemove,
 CartLinesUpdate,
 CartNoteUpdate,
 CartSelectedDeliveryOptionsUpdate,
} from '@shopify/hydrogen';
import {
 cartFormInputAction,
 cartCreateDefault,
 cartGetDefault,
 cartLinesAddDefault,
 cartLinesUpdateDefault,
 cartLinesRemoveDefault,
 cartDiscountCodesUpdateDefault,
 cartBuyerIdentityUpdateDefault,
 cartNoteUpdateDefault,
 cartSelectedDeliveryOptionsUpdateDefault,
} from '@shopify/hydrogen';
import {Cart} from '@shopify/hydrogen/storefront-api-types';
import {parse as parseCookie} from 'worktop/cookie';

type CartApiOptions = Omit<CartQueryOptions, 'getCartId'> & {
 request: Request;
 getCartId?: () => string | undefined;
 setCartId?: (cartId: string, headers: Headers) => void;
};

export type CartApiReturn = {
 getFormInput: (formData: any) => CartFormInput;
 get: (cartInput?: CartFormInput) => Promise<Cart | null | undefined>;
 getCartId: () => string | undefined;
 setCartId: (cartId: string, headers: Headers) => void;
 create: CartQueryReturn<CartCreate>;
 addLine: CartQueryReturn<CartLinesAdd>;
 updateLines: CartQueryReturn<CartLinesUpdate>;
 removeLines: CartQueryReturn<CartLinesRemove>;
 updateDiscountCodes: CartQueryReturn<CartDiscountCodesUpdate>;
 updateBuyerIdentity: CartQueryReturn<CartBuyerIdentityUpdate>;
 updateNote: CartQueryReturn<CartNoteUpdate>;
 updateSelectedDeliveryOption: CartQueryReturn<CartSelectedDeliveryOptionsUpdate>;
};

export function createCartApi(options: CartApiOptions): CartApiReturn {
 const {request} = options;

 // Default get cartId in cookie
 const getCartId =
   options.getCartId ||
   (() => {
     const cookies = parseCookie(request.headers.get('Cookie') || '');
     return cookies.cart ? `gid://shopify/Cart/${cookies.cart}` : undefined;
   });

 // Default set cartId in cookie
 const setCartId =
   options.setCartId ||
   ((cartId: string, headers: Headers) => {
     headers.append('Set-Cookie', `cart=${cartId.split('/').pop()}`);
   });

 const queryOptions = {
   storefront: options.storefront,
   getCartId,
 };

 const cartId = getCartId();
 const cartCreate = cartCreateDefault(queryOptions);

 return {
   getFormInput,
   get: cartGetDefault(queryOptions),
   getCartId,
   setCartId,
   create: cartCreate,
   addLine: async (cartInput: CartLinesAdd) => {
     return cartId
       ? await cartLinesAddDefault(queryOptions)(cartInput)
       : await cartCreate({
           action: CartFormInputAction.CartCreate,
           input: {lines: cartInput.lines},
         });
   },
   updateLines: cartLinesUpdateDefault(queryOptions),
   removeLines: cartLinesRemoveDefault(queryOptions),
   updateDiscountCodes: async (cartInput: CartDiscountCodesUpdate) => {
     return cartId
       ? await cartDiscountCodesUpdateDefault(queryOptions)(cartInput)
       : await cartCreate({
           action: CartFormInputAction.CartCreate,
           input: {discountCodes: cartInput.discountCodes},
         });
   },
   updateBuyerIdentity: async (cartInput: CartBuyerIdentityUpdate) => {
     return cartId
       ? await cartBuyerIdentityUpdateDefault(queryOptions)({
           action: CartFormInputAction.CartBuyerIdentityUpdate,
           buyerIdentity: cartInput.buyerIdentity,
         })
       : await cartCreate({
           action: CartFormInputAction.CartCreate,
           input: {buyerIdentity: cartInput.buyerIdentity},
         });
   },
   updateNote: cartNoteUpdateDefault(queryOptions),
   updateSelectedDeliveryOption:
     cartSelectedDeliveryOptionsUpdateDefault(queryOptions),
 };
}

2. Update your createCartApi import in Remix context in server.ts

+ import {createCartApi} from '~/lib/cart-queries.server';

...
+ const cart = createCartApi({
+ storefront,
+ request,
+ });

const handleRequest = createRequestHandler({
  build: remixBuild,
  mode: process.env.NODE_ENV,
+  getLoadContext: () => ({session, storefront, cart, env}),
});

3. Modify the query you want to change in your createCartApi

 return {
-   get: cartGetDefault(queryOptions),
+   get: async (cartInput?: CartFormInput) => {
+     const cartId = options.getCartId();
+
+    if (!cartId) return null;

+    const {cart} = await options.storefront.query<{
+        cart?: Cart
+      }>(MY_CART_QUERY, {
+      variables: {
+        cartId,
+        numCartLines: cartInput?.numCartLines || 100,
+      },
+      cache: options.storefront.CacheNone(),
+    });

+    return cart;
+ },
+}

+ const MY_CART_QUERY = `#graphql
+   ...
+   cart {
+     id
+     note
+   }
+ `;

Use the original cartGetDefault function and the graphql query as a starting point.

[TBD] Simpler customize cart queries and logic

We've also researched an alternative way to customize default cart queries. We are researching this approach and will update this RFC when we are more convinced to add this to the framework.

const cart = createCartApi(storefront, request)
+ const extendedCart = {…cart, getCart: () => {/* custom stuffs */}}

Cart fragments

We initially don't plan on allowing modification of the default cart fragment since that would make the cart functions signature complex.

We'd love ❤️ to hear your feedback

[blittle]

A few thoughts:

1. Maybe change createCartApi to have a more consistent name with createRequestHandler. Perhaps createCartHandler?
2. I'm not a fan of cart.setCartId with the implicit mutation of the headers object. Why not just const headers = cart.getHeaders(result.cart.id)?
3. I agree that copying the entire cart implementation out seems unfortunate. Like if we add a new method or change things down the road, we'd have to have a migration guide on updating the big ole thing they copied out of Hydrogen.

[blittle]

Another con with the current implementation is the usage of render props means that hydration is required before the user can interact. I don't think this is ideal. If I see the "Add to cart" button, I want to be able to click it immediately, not wait for the whole page to finish loading all the JS. At the very least we should make vanilla JSX children acceptable. Then the user could useFetcher() manually.

[jpmarra]

I recently have been creating a cart via the cart setup documentation and it's been a bit of a headache so it's great to see this abstraction proposal!

One of the things I'm trying to accomplish is use of the BuyNowButton, but this requires the CartProvider. Would this change enable the ability for Buy Now within the Product page?

[blittle]

An example BuyNowButton implementation with this abstraction:

export function BuyNowButton({ variant }) {
  const formInputs = {
    action: CartFormInputAction.CartLinesAdd,
    lines: [
      {
        merchandiseId: variant.id,
        quantity: 1,
      },
    ],
  };
  return (
    <CartForm formInput={formInputs}>
      <button>Buy now</button>
    </CartForm>
  );
}

Then you'd also need to setup an action to accept the buy now operation:

export async function action({ request, context }: ActionArgs) {
  const { cart } = context;
  const headers = new Headers();

  const formData = await request.formData();
  const cartInput = cart.getFormInput(formData);
  const result = await cart.addLine(cartInput);

  cart.setCartId(result.cart.id, headers);

  // The user automatically goes to checkout because of the redirect
  return redirect(result.checkoutUrl, {
    status: 302,
    headers,
  });
}

[benjaminsehl]

Feels like we should provide this out of the box.

[juanpprieto]

I feel the heading [Recommended] Customize cart queries and logic is a bit misleading/confusing.

I think it would be clearer as Advanced (optional) - Customize cart queries and logic

[lordofthecactus]

Thank you. Updated.

[juanpprieto]

Could we also remove this line console.log(`${cartInput.action} result`, result)

[duncan-fairley]

Definitely agree on the need here. Really liking the <CartForm/> approach.

After our first few h2 builds I'm feeling like modifying the cart fragment / query is going to be very common (likely every build) whereas the actions will be pretty consistent (since they dispatch a relatively constrained set of mutations)

I quite liked the way an override cart query could be specified in H1, maybe that's an optional input of createCartApi? I don't think there would be an issue if there were a number of minimum required fields for the cart fragment that would generate an error if not present? That might help with the signature issue.

I also wouldn't hate if the cart route became a bit more magical as long as you could specify custom actions but also understand the reluctance. Makes me wonder if the default actions could just be handled automagically but devs would have the ability to specify custom actions (with different names) that had a different behavior.

My sense is in the overwhelming majority of cases the default action set will be fine as long as the fragment can be updated, I'm not sure we've ever done a headless build where the cart fragment didn't need to be touched.

[frandiox]

Thinking about this purely from the perspective of type safety / codegen, passing a fragment or a full query directly to the function call will make things harder.

It would probably be better if the whole method can be rewritten using storefront.query so you get types automatically. Or maybe it could be simplified to something like the following, where you specify the returned type once (at creation):

const cart = createCartApi(storefront, request, {
  addLine: createCartApi.defaultAddLine<CustomReturnType>({..., fields: 'id name blah'}),
});

That way you don't need to reimplement the whole functionality, just the query/fields and return type 🤔

Would any of this be useful in your experience? Or would still prefer a way to override the query when calling cart.addLine(..., '...')?

[frandiox]

[TBD] Simpler customize cart queries and logic
We've also researched an alternative way to customize default cart queries. We are researching this approach and will update this RFC when we are more convinced to add this to the framework.

const cart = createCartApi(storefront, request)
+ const extendedCart = {…cart, getCart: () => {/* custom stuffs */}}

What about something like the following?

const cart = createCartApi(storefront, request, {
  addLine: () => {} // override existing method
  cutomMethods: {
    doMagic: () => { storefront.mutate(...) } // Add custom methods
  }
});

cart.addLine(...); // Modified
cart.updateLines(...); // Default
cart.doMagic(...); // Custom

This still allows anyone to copy/paste and make their own createCartApi, but it also allows for quick modifications 🤔

---

I feel I've mentioned this somewhere else but just in case, passing request as a parameter might be troublesome because it can have different types depending on the hosting platform (Fetch Request vs Node req, etc.). Maybe we should just pass headers or anything we need specifically from the request (like we do in createStorefrontClient)?

[duncan-fairley]

Really like the idea of defining custom methods / overrides like that.

[blanklob]

Some thoughts here: regards to naming conventions, I believe it would be beneficial to have consistent API names with the Liquid cart form. For example, lines could be renamed to items. Additionally, it would be preferable to place the action outside of the form data object.

export function BuyNowButton({ variant }) {
  const formInputs = {
    items: [
      {
        merchandiseId: variant.id,
        quantity: 1,
      },
    ],
  };
  return (
    <CartForm formInput={formInputs} action={CartFormInputAction.CartLinesAdd}>
      <button>Buy now</button>
    </CartForm>
  );
}

Please note that my familiarity with Hydrogen APIs is limited, and I may be mistaken.

[frehner]

For example, lines could be renamed to items

Good feedback - in general, I agree. In this case, however, I believe we're matching the Storefront API's terminology for these things, which is Line. For example: https://shopify.dev/docs/api/storefront/2023-04/objects/CartLine

It would be great if we could get the Storefront API and Liquid to have a consistent term for them, though. 🤔

[blanklob]

I completely agree with you. I don't think it would make sense to switch the name. I would prefer if it were based on Storefront API since that is the one consumed by Hydrogen. However, aligning both the AJAX Cart API with the Cart Storefront API would be a good idea or something to consider.

[wizardlyhel]

My sense is in the overwhelming majority of cases the default action set will be fine as long as the fragment can be updated, I'm not sure we've ever done a headless build where the cart fragment didn't need to be touched.

@duncan-fairley Thanks for the feedbacks

We have been going back and forth about providing an overridable cart fragment and here are the considerations:

If we allow for overridable cart fragments, there need to be some restriction on the provided cart fragment

For example:

• The provided cart fragment must be named with CartFragment
• It can only use the following query variables: $cartId, $numCartLines, $country, $language (This is due to the fact that the query we use with the cartGetDefault is written this way. If we offer a way to override the variables as well, it would make the entire function so complicated that you might as well write your own cart query using storefront.query and it would be much more clear, in the code, what this function is doing)

If at any point the provided cart fragment is incorrect, debugging this is hard because there is no single place where the entire graphql query for cartGetDefault is complete.

const MY_CART_QUERY_FRAGMENT = `#graphql
  fragment CartFragment on Cart {
    id
    checkoutUrl
    totalQuantity
    lines(first: $numCartLines) {
      edges {
        node {
          id
        }
     }
   }
  }
`;

createCartApi({
  storefront,
  request,
  cartQueryFragment: MY_CART_QUERY_FRAGMENT
});

It would be an anti-pattern if this cart abstraction prevents you from doing what graphql (the language itself) can do on its own

So .. the question would be where do we draw the line between too much magic or not enough magic?

[benjaminsehl]

How do we feel about allowing you to "eject" and get our client scaffolded into your project for you? Is that too risky as it pertains to upgrades in the future?

[wizardlyhel]

All methods used in the CartApi can be exported from the hydrogen package. If the client scaffold contains an ejected version of CartApi, the only thing they may miss out on an upgrade is that if there are new mutation query methods available from the storefront api, for example, cartMetafieldsSet. To add these new query methods, client scaffold just needs to export the new default query method that we will export from the hydrogen package.

[duncan-fairley]

The provided cart fragment must be named with CartFragment

Makes sense

It can only use the following query variables: $cartId, $numCartLines, $country, $language

I don't foresee this being a huge problem, I can't remember a time when I've encountered a need to specify variables inside a cart query beyond language and country.

Debugging queries as it stands is difficult (even when you have control of the entire query) and I've generally fallen back to using the built-in GraphiQL route to debug which seems like it would work relatively well in this instance (only tricky thing would be finding / generating a valid cart ID)

[benjaminsehl]

Debugging queries as it stands is difficult (even when you have control of the entire query) and I've generally fallen back to using the built-in GraphiQL route to debug which seems like it would work relatively well in this instance (only tricky thing would be finding / generating a valid cart ID)

@blittle — more signal that we should auto-respond with the query in our error response and a deep link to Graphiql for you to debug. cc: @frandiox

[frandiox]

I was thinking precisely about this a few days ago. If we follow a certain pattern for our messages, like [h2:info] ... or [h2:error] ..., we could detect this from the CLI and change it to a better format, and optionally output a link to GraphiQL with the query included in the URL.

[wizardlyhel]

After some discussion within the team, we have arrive at this version of createCartApi:

// Basic usage
const cart = createCartApi({
  storefront,
  requestHeaders: request.headers,
});

// Override cart fragments
const cart = createCartApi({
  storefront,
  requestHeaders: request.headers,
  cartQueryFragment: CART_QUERY_FRAGMENT, // override cart fragment for cartGetDefault
  cartMutateFragment: CART_MUTATE_FRAGMENT, // override cart fragment for all other mutation queries except for metafieldsSet and metafieldDelete
});

// Add or override cart methods
const cart = createCartApi({
  storefront,
  requestHeaders: request.headers,
  customMethods: {
    addLine: () => {
      return await storefront.mutate(...),
    }, // overrides cart.addLine
    magic: () => {}, // adds a new method and can be invoked with `cart.magic()`
  }
});

The user supplied cart fragments will have strict rules of the fragment name and variable usage.
As for making errors from storefront api more readable and debuggable, we'll tackle that in another issue.

See #786 for implementation details

[duncan-fairley]

Very excited about where this landed. Sincerely appreciate the team's willingness to incorporate feedback and iterate toward a solid solution.

[duncan-fairley]

Had a random thought on this.

We've had a long history of significant issues on international headless sites that have arisen from the store locale and cartBuyerIdentity falling out of sync. We've had difficultly when the buyerIdenity is exclusively changed when the user switches locales because that doesn't seem to reliably cover all cases of a user migrating between locales.

We've started to roll out a change to the demo store getCart function to more reliably address this issue:

export async function getCart(storefront: Storefront, cartId: string) {
  let { cart } = await storefront.query<CartQuery>(CART_QUERY, {
    variables: {
      cartId,
      country: storefront.i18n.country,
      language: storefront.i18n.language,
    },
    cache: storefront.CacheNone(),
  })

  //If there is a mismatch between the country code in the cart buyerIdentity and the request,
  //update the cart buyerIdentity to match the request
  const cartBuyerCountryCode = cart?.buyerIdentity?.countryCode
  const requestCountryCode = storefront?.i18n?.country
  if (cartBuyerCountryCode && requestCountryCode && cartBuyerCountryCode !== requestCountryCode) {
    const { cartBuyerIdentityUpdate } = await storefront.mutate<CartBuyerIdentityUpdateMutation>(
      CART_BUYER_IDENTITY_UPDATE_MUTATION,
      {
        variables: {
          cartId,
          buyerIdentity: { countryCode: requestCountryCode },
        },
      },
    )
    cart = cartBuyerIdentityUpdate?.cart
  }
  return cart
}

I'm waffling on whether something like this would make sense inside the abstraction or implemented in userland. I know the barrier to solving this issue on the merchant / agency side is high since you quickly get into relatively complex issues around loader state and validation to avoid infinite loops.

Though this solution above definitely feels like a hack but we've had trouble handling it gracefully with an action (though I'm sure there is a way). This method does feel more robust and harder to break since it will always default to the app's locale.

[wizardlyhel]

Trying to imagine what event scenario generates this situation ..
In the demo-store, when we change locale, we also sent a mutation request to update buyer identity to the correct locale.

So in order for your case to happen .. directly visit a locale page (ie. hydrogen.shop/EN-UK) and auto-add an line item?
Because the default currency of the shop is USD, the cart is showing USD instead of Pound.
Mmm .. but we could update the buyer identity right at the request where we add line.

Would you provide a scenario that would reproduce this situation? I don't like cart.get to be potentially blocked by an mutation request to update buyer identity

[duncan-fairley]

Yeah, agreed @wizardlyhel, even though it would only block the call in cases of buyerIdentity mismatch it still doesn't seem like a great idea.

The more I've thought about this the more I've realized that many of the issues we'd historically encountered have been a result of the fact that another headless framework we used created a cart automatically for every session (vs only after the first item is added to the cart).

I the most common scenario I can think of is that somebody adds an item to cart while browsing in the base region then returns to the site through a Google search which may be via a properly regionalized link. They'd have a region mismatch that would result in a weird state where the PDP and Cart price wouldn't match. Historically it's seemed to happen for us more often than you would expect.

Interestingly when I try and replicate hydrogen.shop my cart doesn't persist at all... That may be a separate issue though.
https://github.com/Shopify/hydrogen/assets/995071/4b7e1b2d-740f-4199-8a36-50d2e002f4e1

Regardless, probably ultimately an edge-case but wanted to bring it up in case there was a solution to binding the app locale and the cart locale more reliably.

[wizardlyhel]

Yes - I can reproduce this with a locale and add an item to cart, then manually navigate to a different locale
(Couldn't reproduce the lost cart you had in the video)

Mmm .. I think this is more of a business logic preference rather than something that should be baked into the abstraction.

Think of it like this ...
I shop on hydrogen.shop in CAD most of the time. One day, I travel to UK and decided to do some shopping on hydrogen.shop. Regionally, Google search returned me the link hydrogen.shop/en-gb. Since I have an active cart, the cart is displayed in CAD.

At this point, we can choose either:

• Sync the cart so the price is display in pounds .. or
• Ask the visitor which currency do they want to display in

[duncan-fairley]

Yeah, I think that's the right call @wizardlyhel. There's some nuance to how each merchant may want to handle this case.

[osseonews]

Just found this repo. As someone who has done headless e-commerce for a few years now, I think your concerns about doing the cart on the client side are misplaced and the benefits of doing cart mutations on the server are overstated and complicate issues which are already solved. For applications in React (which this is), I am pretty sure the better option that actually is more scaleable and will actually work well in production is client-side using libraries like React-Query (tanstack query) or useSwr. But may React Query doesn't work well in Remix? Will be interesting to compare a client-side implementation of the Cart vs the server option.

[wizardlyhel]

Server-side or client-side, they both have their benefits. The question is what are the goals you are trying to achieve. Hydrogen's goal is to be performant and secure for both server side and client side. So bundle size, JS execution time both matters to us.

Server-side cart mutation requests

• You have control over what you ship to the client side. For example, you need inventory count to show if a product is close to being sold out but you don't want to show or give the possibilities of other sites scraping your site for inventory count.
• Less data manipulation code on the client-side = less JS shipped to client

Query caching

React-query have the ability to cache results. We really like that concept but react-query is also a really heavy graphql library that would take up the limited space that a Cloudflare worker allows (1MB limit - the limit got raised recently but still, we should aim for small bundles)

Hydrogen implemented sub request caching with Cloudflare's Cache API to have similar ability to cache graphql results. We stringify graphql queries so that they are just string representation. We compress the requirements to what is absolutely necessary to make a graphql query request and strip away anything else that just bloats the bundle.

[wizardlyhel]

The cart abstraction is available on next tag.

To test it out, in your package.json, update the following

  "dependencies": {
    "@shopify/cli-hydrogen": "next",
    "@shopify/hydrogen": "next",
    "@shopify/remix-oxygen": "next",

Official docs are coming soon, here are some quick step to get you started:

Step 1: Create a cart instance with createCartHandler

The createCartHandler function returns an object instance for you to interact with Storefront API cart queries. It allows you to easily interact with the cart.

In your server.js file, create your cart handler inside the server fetch handler.

const cart = createCartHandler({
  storefront, // storefront is created by the createStorefrontClient
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
});

Next, pass your cart instance to the getLoadContext function.

const handleRequest = createRequestHandler({
  build: remixBuild,
  mode: process.env.NODE_ENV,
  getLoadContext: () => ({
    session,
    waitUntil,
    storefront,
    env,
    cart, // Passed in cart instance
  }),
});

If you're using Typescript, then add the HydrogenCart type to remix.env.d.ts to have a type association.
If you've added custom methods to the createCartHandler, then use the HydrogenCartCustom type instead.

import type {HydrogenCart} from '@shopify/hydrogen';

declare module '@shopify/remix-oxygen' {
  export interface AppLoadContext {
    waitUntil: ExecutionContext['waitUntil'];
    session: HydrogenSession;
    storefront: Storefront;
    cart: HydrogenCart;  // The type declaration for cart
    env: Env;
  }
}

Step 2: Decide how you want to manage the cart id

The createCartHandler function doesn't have a preference on how and where you store the cart ID. Hydrogen provides the following default methods for getting and setting a cart ID:

• cartGetIdDefault(requestHeaders: Headers): Retrieves the cart ID from the request header cookie. The cookie name must be cart.
• cartSetIdDefault(): Returns a function that accepts a new cart ID and sets a cookie called cart=<new_cart_id> in the returned Headers object. By default, cartSetIdDefault() sets a session cookie. This means the cookie disappears when the user closes the browser.

Update cookie settings by passing options to cartSetIdDefault.

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault({
    maxage: 60 * 60 * 24 * 365, // One year expiry
  }),
});

Step 3: Create a Remix action to handle different form requests

Create a Remix action to handle the different cart actions. We suggest using a single cart route, and switching on the different actions. Use the cart handler, which is available on the action context, to send cart mutation requests to the Storefront API.

import {CartForm} from '@shopify/hydrogen';
import invariant from 'tiny-invariant';

export async function action({request, context}) {
  const {cart} = context;

  const formData = await request.formData();
  const {action, inputs} = CartForm.getFormInput(formData);

  let result;

  switch(action) {
    case CartForm.ACTIONS.LinesAdd:
      result = await cart.addLines(inputs.lines);
      break;
    case CartForm.ACTIONS.LinesUpdate:
      result = await cart.updateLines(inputs.lines);
      break;
    case CartForm.ACTIONS.LinesRemove:
      result = await cart.removeLines(inputs.lineIds);
      break;
    default:
      invariant(false, `${action} cart action is not defined`);
  }

  // The Cart ID might change after each mutation, so update it each time.
  const headers = cart.setCartId(result.cart.id);

  return json(
    result,
    {status: 200, headers},
  );
}

Step 4: Add cart items

Use the CartForm component to create an add to cart button. The component submits a form request to the /cart route's action when users interact with the button. You can use this component anywhere in the app.

import {CartForm} from '@shopify/hydrogen';

export default function AddToCartButton({lines}) {
  return (
    <CartForm
      route="/cart"
      action={CartForm.ACTIONS.LinesAdd}
      inputs={
        {lines}
      }
    >
      <button>
        Add to cart
      </button>
    </CartForm>
  );
}

Customizing the cart handler

You can modify the cart query fragment. See the default CartApiQuery fragment for reference.

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  cartQueryFragment: CART_QUERY_FRAGMENT, // Your custom cart query fragment
});

You can modify the cart mutation fragment. See the default CartApiMutation fragment for reference.

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  cartMutateFragment: CART_MUTATE_FRAGMENT, // Your custom cart mutate fragment
});

(unstable) customMethods

Would like to have some feedbacks on this DX.

If you have common cart operations that you would like to reuse across your app, you can add custom methods to your cart handler. For example, add and remove an item from the cart at the same time.

const cartQueryOptions = {
  storefront,
  getCartId: cartGetIdDefault(request.headers),
};

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  customMethods__unstable: {
    editInLine: async (addLines, removeLineIds, optionalParams) => {
      // Using Hydrogen default cart query methods

      // Add line items
      await cartLinesAddDefault(cartQueryOptions)(addLines, optionalParams);

      // Remove line items
      return await cartLinesRemoveDefault(cartQueryOptions)(
        removeLineIds,
        optionalParams,
      );
    }
  },
});

Hydrogen provides out of the box multiple methods for interacting with the cart. You can override any default method with your own logic. For example, you can override the updateAttributes to do something custom with cart attributes:

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  customMethods__unstable: {
    updateAttributes: async (attributes, optionalParams) => {

      // Do something with attributes

      // Make a mutation query to update cart attributes
      const {cartAttributesUpdate} = await options.storefront.mutate(CART_ATTRIBUTES_UPDATE_MUTATION, {
        variables: {
          cartId: optionalParams?.cartId || options.getCartId(),
          attributes,
        },
      });
      return cartAttributesUpdate;
    },
  },
});

export const CART_ATTRIBUTES_UPDATE_MUTATION = `#graphql
  mutation cartAttributesUpdate(
    $cartId: ID!
    $attributes: [CartAttributeInput!]!
  ) {
    cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
      cart {
        id
      }
    }
  }
`;

The default cart handler includes basic cart logic. If you override these methods, you need to implement the cart logic as well. For example when adding a line item to a cart, you would need to implement the logic needed to create a cart with the line item.

The following methods include create cart logic::

• addLines - If a cart doesn't exist, then create a cart with the line items.
• setMetafields - If a cart doesn't exist, then create a cart with the metafields applied.
• updateAttributes - If a cart doesn't exist, then create a cart with the attributes applied.
• updateBuyerIdentity - If a cart doesn't exist, then create a cart with the buyer identity applied.
• updateDiscountCode - If a cart doesn't exist, then create a cart with the discount applied.
• updateNote - If a cart doesn't exist, then create a cart with the note applied.

[duncan-fairley]

Awesome, yeah, just trying to get as far ahead on it as we can. The next branch is super helpful to be ahead of the launch. We've got 8 storefronts to refactor 😅

[wizardlyhel]

@duncan-fairley We found a bug. Don't do the following for now:

export async function loader({context}: LoaderArgs) {
   return defer({
     cart: context.cart.get()
   })
}

For some reason, it's not resolving the cart.get promise like I expect it should in a defer.

You can still do

export async function loader({context}: LoaderArgs) {
   return json({
     cart: context.cart.get()
   })
}

Here is reference of what we do on demo store for now #1081

[wizardlyhel]

I got a 500 error.

Error: The deferred data for cart was not resolved, did you forget to return data from a deferred promise?

[wizardlyhel]

Okay - all fixed - make sure to npm install to bring in the latest next version

[duncan-fairley]

Awesome, updating

[wizardlyhel]

Released cart abstraction under 2023.7.0 version
Official docs: https://shopify.dev/docs/custom-storefronts/hydrogen/cart

[duncan-fairley]

Congrats team! Updating now

[wizardlyhel]

If interested, I have also started a discussion thread about optimistic UI for <CartForm>
#1158

[thebiggianthead]

Hey! I updated our hydrogen-sanity-demo template to use the new approach for the cart yesterday. Super easy to do and like the new approach!

One small bit of feedback was that it'd be great to be able to pass more props to the <CartForm /> component. I had a scenario where I wanted to add a class to the form element it renders and it doesn't seem possible right now.

[wizardlyhel]

Curious .. anyone here is using customMethods__unstable?

We are about to upgrade to storefront API 2023-10 and I am wondering if there are any feedbacks to this property before I remove the unstable tag.

[chrisvltn]

Not sure if I should post it here or create a new post :)

We want to have the cart synchronized between the customer's devices, and for this we're saving the ID in the customer's metafield.

Sadly the getCartId and setCartId are right now synchronous. Maybe it would make sense having them synchronous instead. This would give a bit more flexibility on where we want to get the cart ID from (as it seems this is the whole point of having this method configurable)

Example:

const cart = createCartHandler({
  storefront,
  getCartId: async () => {
    const {customer} = await storefront.query(/* Customer cartId query with some short cache */);
    return customer.cartId;
  },
  setCartId: (cartId) => {
    waitUntil(() => storefront.mutation(/* cartId mutation */));
    return {};
  },
});

[wizardlyhel]

@chrisvltn I see what you are trying to do but the approach you have will be very unstable and becomes a query performance bottleneck for every cart queries and mutations in the project. It doesn't make sense for getCartId to be an async function.

In your situation, you should call for query for customer metafield for that stored cartId upon logging in and store that cartId in a cookie header (or use cart.setCartId) so that it can be readily be accessed in a request header. This customer metafield won't ever change until another setCartId (which you have a waitUntil to update customer metafield) is called. The stored cartId for a logged in customer is only useful at the moment when the customer is logging in.

[rohit-jaxxon]

getting an error now:

│ In Hydrogen's storefront.query: │
│ │
│ Variable $numCartLines is declared by CartQuery but not used │
│ Request ID: f179802f-0fd4-4a69-aa12-582722b8a9b2-1709762360 │
│ │
│ To debug the query CartQuery, try it in GraphiQL ( │
│ http://localhost:3000/graphiql?query=query%20CartQuery(%20%24cartId%3A%20ID!%20%24numCartLin │
│ es%3A%20Int%20%3D%20100%20%24country%3A%20CountryCode%20%3D%20ZZ%20%24language%3A%20Language │
│ Code%20)%20%40inContext(country%3A%20%24country%2C%20language%3A%20%24language)%20%7B%20cart │
│ (id%3A%20%24cartId)%20%7B%20...CartApiQuery%20%7D%20%7D%20fragment%20CartApiQuery%20on%20Car │
│ t%20%7B%20id%20totalQuantity%20checkoutUrl%20note%20%7D&variables=%7B%22cartId%22%3A%22gid%3 │
│ A%2F%2Fshopify%2FCart%2FZ2NwLXVzLWNlbnRyYWwxOjAxSFI5REEzRDgwQTlLTUs5WUNBVDNRSDRD%22%2C%22cou │
│ ntry%22%3A%22US%22%2C%22language%22%3A%22EN%22%7D ). │
│ │
│ To investigate the issue, examine this stack trace: │
│ at loader (app/root.jsx:111) │
│ cart: cart.get(),

[wizardlyhel]

make sure your custom fragment for cartQueryFragment follow this default cart query

Make sure your lines query takes in $numCartLines

ex: lines(first: $numCartLines) {

This is default to query 100 cart lines

[rohit-jaxxon]

Hi there, this time I'm using this:

const CART_MUTATE_FRAGMENT = #graphql fragment CartApiMutation on Cart { id totalQuantity checkoutUrl lines(first: $numCartLines) { edges { node { id quantity discountAllocations { discountedAmount { amount currencyCode } } } } } } ;

and getting this error:

In Hydrogen's storefront.mutation: │
│ │
│ Variable $numCartLines is used by CartApiMutation but not declared │
│ Request ID: f8854a3e-622c-46bb-9d84-56fb029d8adb-1709774607 │
│ │
│ To debug the mutation cartLinesUpdate, try it in GraphiQL ( │
│ http://localhost:3000/graphiql?query=mutation%20cartLinesUpdate(%20%24cartId%3A%20ID!%20%24l │
│ ines%3A%20%5BCartLineUpdateInput!%5D!%20%24language%3A%20LanguageCode%20%24country%3A%20Coun │
│ tryCode%20)%20%40inContext(country%3A%20%24country%2C%20language%3A%20%24language)%20%7B%20c │
│ artLinesUpdate(cartId%3A%20%24cartId%2C%20lines%3A%20%24lines)%20%7B%20cart%20%7B%20...CartA │
│ piMutation%20%7D%20userErrors%20%7B%20...CartApiError%20%7D%20%7D%20%7D%20fragment%20CartApi │
│ Mutation%20on%20Cart%20%7B%20id%20totalQuantity%20checkoutUrl%20lines(first%3A%20%24numCartL │
│ ines)%20%7B%20edges%20%7B%20node%20%7B%20id%20quantity%20discountAllocations%20%7B%20discoun │
│ tedAmount%20%7B%20amount%20currencyCode%20%7D%20%7D%20%7D%20%7D%20%7D%20%7D%20fragment%20Car │
│ tApiError%20on%20CartUserError%20%7B%20message%20field%20code%20%7D&variables=%7B%22cartId%2 │
│ 2%3A%22gid%3A%2F%2Fshopify%2FCart%2FZ2NwLXVzLWNlbnRyYWwxOjAxSFBOVjFKSEtCUTZBUjc2NDE3UVZQTUUw │
│ %22%2C%22lines%22%3A%5B%7B%22id%22%3A%22gid%3A%2F%2Fshopify%2FCartLine%2F7f22f134-1ecd-4264- │
│ 8da8-a87ed55f6bb9%3Fcart%3DZ2NwLXVzLWNlbnRyYWwxOjAxSFBOVjFKSEtCUTZBUjc2NDE3UVZQTUUw%22%2C%22 │
│ quantity%22%3A2%7D%5D%2C%22country%22%3A%22US%22%2C%22language%22%3A%22EN%22%7D ). │
│ │
│ To investigate the issue, examine this stack trace: │
│ at action5 (app/routes/($locale).cart.jsx:32) │
│ result = await cart.updateLines(inputs.lines);

[rohit-jaxxon]

Hi there, just following up on this. Is there a working version/example for this that I can follow?

[blittle]

Yep, in our starter template: https://github.com/Shopify/hydrogen/blob/main/templates/skeleton/server.ts#L71