Next.js Commerce refresh. (#966)

We're making some updates to Next.js Commerce. Everything prior to this commit marks what we're calling [`v1`](https://github.com/vercel/commerce/releases/tag/v1) as a point in time to be able to reference and still use going into the future. The current architecture of Commerce is a multi-vendor, interoperable solution, including:

- [Shopify](https://shopify.vercel.store/)
- [Swell](https://swell.vercel.store/)
- [BigCommerce](https://bigcommerce.vercel.store/)
- [Vendure](https://vendure.vercel.store/)
- [Saleor](https://saleor.vercel.store/)
- [Ordercloud](https://ordercloud.vercel.store/)
- [Spree](https://spree.vercel.store/)
- [Kibo Commerce](https://kibocommerce.vercel.store/)
- [Commerce.js](https://commercejs.vercel.store/)
- [SalesForce Cloud Commerce](https://salesforce-cloud-commerce.vercel.store/)

All features can be toggled on or off, and it's easy to change between commerce providers. To support this, we needed to create a ["commerce metaframework"](d1d9e8c434/packages/commerce/new-provider.md) where providers could confirm to an API spec to add support for Next.js Commerce. While this worked and was successful for `v1`, we have different design goals and ambitions for `v2`.

**What You Need To Know**

- `v1` will not be updated moving forward. If you need to reference `v1`, you will still be able to clone and deploy the version tagged at this release.
- `v2` will be shifting to be a single provider vs. provider agnostic. Other providers are welcome to fork this repository and swap out the underlying `lib/` implementation that connects to the selected commerce provider (Shopify). This architecture was chosen to reduce the surface area of the codebase, remove the intermediate metaframework layer for provider-interoperability, and enable usage with the latest Next.js and React features.
- We will be sharing more about `v2` in the future as we continue to iterate before the marked release.

lib/shopify/fragments/cart.ts

@@ -0,0 +1,49 @@
+import productFragment from './product';
+
+const cartFragment = /* GraphQL */ `
+  fragment cart on Cart {
+    id
+    checkoutUrl
+    cost {
+      subtotalAmount {
+        amount
+        currencyCode
+      }
+      totalAmount {
+        amount
+        currencyCode
+      }
+      totalTaxAmount {
+        amount
+        currencyCode
+      }
+    }
+    lines(first: 100) {
+      edges {
+        node {
+          id
+          quantity
+          cost {
+            totalAmount {
+              amount
+              currencyCode
+            }
+          }
+          merchandise {
+            ... on ProductVariant {
+              id
+              title
+              product {
+                ...product
+              }
+            }
+          }
+        }
+      }
+    }
+    totalQuantity
+  }
+  ${productFragment}
+`;
+
+export default cartFragment;

lib/shopify/fragments/image.ts

@@ -0,0 +1,10 @@
+const imageFragment = /* GraphQL */ `
+  fragment image on Image {
+    url
+    altText
+    width
+    height
+  }
+`;
+
+export default imageFragment;

lib/shopify/fragments/product.ts

@@ -0,0 +1,63 @@
+import imageFragment from './image';
+import seoFragment from './seo';
+
+const productFragment = /* GraphQL */ `
+  fragment product on Product {
+    id
+    handle
+    availableForSale
+    title
+    description
+    descriptionHtml
+    options {
+      id
+      name
+      values
+    }
+    priceRange {
+      maxVariantPrice {
+        amount
+        currencyCode
+      }
+      minVariantPrice {
+        amount
+        currencyCode
+      }
+    }
+    variants(first: 250) {
+      edges {
+        node {
+          id
+          title
+          availableForSale
+          selectedOptions {
+            name
+            value
+          }
+          price {
+            amount
+            currencyCode
+          }
+        }
+      }
+    }
+    featuredImage {
+      ...image
+    }
+    images(first: 20) {
+      edges {
+        node {
+          ...image
+        }
+      }
+    }
+    seo {
+      ...seo
+    }
+    tags
+  }
+  ${imageFragment}
+  ${seoFragment}
+`;
+
+export default productFragment;

lib/shopify/fragments/seo.ts

@@ -0,0 +1,8 @@
+const seoFragment = /* GraphQL */ `
+  fragment seo on SEO {
+    description
+    title
+  }
+`;
+
+export default seoFragment;

lib/shopify/index.ts

@@ -0,0 +1,361 @@
+import { HIDDEN_PRODUCT_TAG, SHOPIFY_GRAPHQL_API_ENDPOINT } from 'lib/constants';
+import { isShopifyError } from 'lib/type-guards';
+import {
+  addToCartMutation,
+  createCartMutation,
+  editCartItemsMutation,
+  removeFromCartMutation
+} from './mutations/cart';
+import { getCartQuery } from './queries/cart';
+import {
+  getCollectionProductsQuery,
+  getCollectionQuery,
+  getCollectionsQuery
+} from './queries/collection';
+import { getMenuQuery } from './queries/menu';
+import { getPageQuery } from './queries/page';
+import {
+  getProductQuery,
+  getProductRecommendationsQuery,
+  getProductsQuery
+} from './queries/product';
+import {
+  Cart,
+  Collection,
+  Connection,
+  Menu,
+  Page,
+  Product,
+  ShopifyAddToCartOperation,
+  ShopifyCart,
+  ShopifyCartOperation,
+  ShopifyCollection,
+  ShopifyCollectionOperation,
+  ShopifyCollectionProductsOperation,
+  ShopifyCollectionsOperation,
+  ShopifyCreateCartOperation,
+  ShopifyMenuOperation,
+  ShopifyPageOperation,
+  ShopifyProduct,
+  ShopifyProductOperation,
+  ShopifyProductRecommendationsOperation,
+  ShopifyProductsOperation,
+  ShopifyRemoveFromCartOperation,
+  ShopifyUpdateCartOperation
+} from './types';
+
+const domain = process.env.SHOPIFY_STORE_DOMAIN!;
+const endpoint = process.env.SHOPIFY_STORE_DOMAIN! + SHOPIFY_GRAPHQL_API_ENDPOINT;
+const key = process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN!;
+
+type ExtractVariables<T> = T extends { variables: object } ? T['variables'] : never;
+
+export async function shopifyFetch<T>({
+  query,
+  variables,
+  headers,
+  cache = 'force-cache'
+}: {
+  query: string;
+  variables?: ExtractVariables<T>;
+  headers?: HeadersInit;
+  cache?: RequestCache;
+}): Promise<{ status: number; body: T } | never> {
+  try {
+    const result = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Shopify-Storefront-Access-Token': key,
+        ...headers
+      },
+      body: JSON.stringify({
+        ...(query && { query }),
+        ...(variables && { variables })
+      }),
+      cache,
+      next: { revalidate: 900 } // 15 minutes
+    });
+
+    const body = await result.json();
+
+    if (body.errors) {
+      throw body.errors[0];
+    }
+
+    return {
+      status: result.status,
+      body
+    };
+  } catch (e) {
+    if (isShopifyError(e)) {
+      throw {
+        status: e.status || 500,
+        message: e.message,
+        query
+      };
+    }
+
+    throw {
+      error: e,
+      query
+    };
+  }
+}
+
+const removeEdgesAndNodes = (array: Connection<any>) => {
+  return array.edges.map((edge) => edge?.node);
+};
+
+const reshapeCart = (cart: ShopifyCart): Cart => {
+  if (!cart.cost?.totalTaxAmount) {
+    cart.cost.totalTaxAmount = {
+      amount: '0.0',
+      currencyCode: 'USD'
+    };
+  }
+
+  return {
+    ...cart,
+    lines: removeEdgesAndNodes(cart.lines)
+  };
+};
+
+const reshapeCollection = (collection: ShopifyCollection): Collection | undefined => {
+  if (!collection) {
+    return undefined;
+  }
+
+  return {
+    ...collection,
+    path: `/search/${collection.handle}`
+  };
+};
+
+const reshapeCollections = (collections: ShopifyCollection[]) => {
+  const reshapedCollections = [];
+
+  for (const collection of collections) {
+    if (collection) {
+      const reshapedCollection = reshapeCollection(collection);
+
+      if (reshapedCollection) {
+        reshapedCollections.push(reshapedCollection);
+      }
+    }
+  }
+
+  return reshapedCollections;
+};
+
+const reshapeProduct = (product: ShopifyProduct, filterHiddenProducts: boolean = true) => {
+  if (!product || (filterHiddenProducts && product.tags.includes(HIDDEN_PRODUCT_TAG))) {
+    return undefined;
+  }
+
+  const { images, variants, ...rest } = product;
+
+  return {
+    ...rest,
+    images: removeEdgesAndNodes(images),
+    variants: removeEdgesAndNodes(variants)
+  };
+};
+
+const reshapeProducts = (products: ShopifyProduct[]) => {
+  const reshapedProducts = [];
+
+  for (const product of products) {
+    if (product) {
+      const reshapedProduct = reshapeProduct(product);
+
+      if (reshapedProduct) {
+        reshapedProducts.push(reshapedProduct);
+      }
+    }
+  }
+
+  return reshapedProducts;
+};
+
+export async function createCart(): Promise<Cart> {
+  const res = await shopifyFetch<ShopifyCreateCartOperation>({
+    query: createCartMutation,
+    cache: 'no-store'
+  });
+
+  return reshapeCart(res.body.data.cartCreate.cart);
+}
+
+export async function addToCart(
+  cartId: string,
+  lines: { merchandiseId: string; quantity: number }[]
+): Promise<Cart> {
+  const res = await shopifyFetch<ShopifyAddToCartOperation>({
+    query: addToCartMutation,
+    variables: {
+      cartId,
+      lines
+    },
+    cache: 'no-store'
+  });
+  return reshapeCart(res.body.data.cartLinesAdd.cart);
+}
+
+export async function removeFromCart(cartId: string, lineIds: string[]): Promise<Cart> {
+  const res = await shopifyFetch<ShopifyRemoveFromCartOperation>({
+    query: removeFromCartMutation,
+    variables: {
+      cartId,
+      lineIds
+    },
+    cache: 'no-store'
+  });
+
+  return reshapeCart(res.body.data.cartLinesRemove.cart);
+}
+
+export async function updateCart(
+  cartId: string,
+  lines: { id: string; merchandiseId: string; quantity: number }[]
+): Promise<Cart> {
+  const res = await shopifyFetch<ShopifyUpdateCartOperation>({
+    query: editCartItemsMutation,
+    variables: {
+      cartId,
+      lines
+    },
+    cache: 'no-store'
+  });
+
+  return reshapeCart(res.body.data.cartLinesUpdate.cart);
+}
+
+export async function getCart(cartId: string): Promise<Cart | null> {
+  const res = await shopifyFetch<ShopifyCartOperation>({
+    query: getCartQuery,
+    variables: { cartId },
+    cache: 'no-store'
+  });
+
+  if (!res.body.data.cart) {
+    return null;
+  }
+
+  return reshapeCart(res.body.data.cart);
+}
+
+export async function getCollection(handle: string): Promise<Collection | undefined> {
+  const res = await shopifyFetch<ShopifyCollectionOperation>({
+    query: getCollectionQuery,
+    variables: {
+      handle
+    }
+  });
+
+  return reshapeCollection(res.body.data.collection);
+}
+
+export async function getCollectionProducts(handle: string, limit?: number): Promise<Product[]> {
+  const res = await shopifyFetch<ShopifyCollectionProductsOperation>({
+    query: getCollectionProductsQuery,
+    variables: {
+      handle,
+      first: limit
+    }
+  });
+
+  return reshapeProducts(removeEdgesAndNodes(res.body.data.collection.products));
+}
+
+export async function getCollections(): Promise<Collection[]> {
+  const res = await shopifyFetch<ShopifyCollectionsOperation>({ query: getCollectionsQuery });
+  const shopifyCollections = removeEdgesAndNodes(res.body?.data?.collections);
+  const collections = [
+    {
+      handle: '',
+      title: 'All',
+      description: 'All products',
+      seo: {
+        title: 'All',
+        description: 'All products'
+      },
+      path: '/search'
+    },
+    // Filter out the `hidden` collections.
+    // Collections that start with `hidden-*` need to be hidden on the search page.
+    ...reshapeCollections(shopifyCollections).filter(
+      (collection) => !collection.handle.startsWith('hidden')
+    )
+  ];
+
+  return collections;
+}
+
+export async function getMenu(handle: string): Promise<Menu[]> {
+  const res = await shopifyFetch<ShopifyMenuOperation>({
+    query: getMenuQuery,
+    variables: {
+      handle
+    }
+  });
+
+  return (
+    res.body?.data?.menu?.items.map((item: { title: string; url: string }) => ({
+      title: item.title,
+      path: item.url.replace(domain, '').replace('/collections', '/search').replace('/pages', '')
+    })) || []
+  );
+}
+
+export async function getPage(handle: string): Promise<Page> {
+  const res = await shopifyFetch<ShopifyPageOperation>({
+    query: getPageQuery,
+    variables: { handle }
+  });
+
+  return res.body.data.pageByHandle;
+}
+
+export async function getProduct(handle: string): Promise<Product | undefined> {
+  const res = await shopifyFetch<ShopifyProductOperation>({
+    query: getProductQuery,
+    variables: {
+      handle
+    }
+  });
+
+  return reshapeProduct(res.body.data.product, false);
+}
+
+export async function getProductRecommendations(productId: string): Promise<Product[]> {
+  const res = await shopifyFetch<ShopifyProductRecommendationsOperation>({
+    query: getProductRecommendationsQuery,
+    variables: {
+      productId
+    }
+  });
+
+  return reshapeProducts(res.body.data.productRecommendations);
+}
+
+export async function getProducts({
+  query,
+  reverse,
+  sortKey
+}: {
+  query?: string;
+  reverse?: boolean;
+  sortKey?: string;
+}): Promise<Product[]> {
+  const res = await shopifyFetch<ShopifyProductsOperation>({
+    query: getProductsQuery,
+    variables: {
+      query,
+      reverse,
+      sortKey
+    }
+  });
+
+  return reshapeProducts(removeEdgesAndNodes(res.body.data.products));
+}

lib/shopify/mutations/cart.ts

@@ -0,0 +1,45 @@
+import cartFragment from '../fragments/cart';
+
+export const addToCartMutation = /* GraphQL */ `
+  mutation addToCart($cartId: ID!, $lines: [CartLineInput!]!) {
+    cartLinesAdd(cartId: $cartId, lines: $lines) {
+      cart {
+        ...cart
+      }
+    }
+  }
+  ${cartFragment}
+`;
+
+export const createCartMutation = /* GraphQL */ `
+  mutation createCart($lineItems: [CartLineInput!]) {
+    cartCreate(input: { lines: $lineItems }) {
+      cart {
+        ...cart
+      }
+    }
+  }
+  ${cartFragment}
+`;
+
+export const editCartItemsMutation = /* GraphQL */ `
+  mutation editCartItems($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+    cartLinesUpdate(cartId: $cartId, lines: $lines) {
+      cart {
+        ...cart
+      }
+    }
+  }
+  ${cartFragment}
+`;
+
+export const removeFromCartMutation = /* GraphQL */ `
+  mutation removeFromCart($cartId: ID!, $lineIds: [ID!]!) {
+    cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+      cart {
+        ...cart
+      }
+    }
+  }
+  ${cartFragment}
+`;

lib/shopify/queries/cart.ts

@@ -0,0 +1,10 @@
+import cartFragment from '../fragments/cart';
+
+export const getCartQuery = /* GraphQL */ `
+  query getCart($cartId: ID!) {
+    cart(id: $cartId) {
+      ...cart
+    }
+  }
+  ${cartFragment}
+`;

lib/shopify/queries/collection.ts

@@ -0,0 +1,51 @@
+import productFragment from '../fragments/product';
+import seoFragment from '../fragments/seo';
+
+const collectionFragment = /* GraphQL */ `
+  fragment collection on Collection {
+    handle
+    title
+    description
+    seo {
+      ...seo
+    }
+  }
+  ${seoFragment}
+`;
+
+export const getCollectionQuery = /* GraphQL */ `
+  query getCollection($handle: String!) {
+    collection(handle: $handle) {
+      ...collection
+    }
+  }
+  ${collectionFragment}
+`;
+
+export const getCollectionsQuery = /* GraphQL */ `
+  query getCollections {
+    collections(first: 100, sortKey: TITLE) {
+      edges {
+        node {
+          ...collection
+        }
+      }
+    }
+  }
+  ${collectionFragment}
+`;
+
+export const getCollectionProductsQuery = /* GraphQL */ `
+  query getCollectionProducts($handle: String!, $first: Int = 100) {
+    collection(handle: $handle) {
+      products(first: $first) {
+        edges {
+          node {
+            ...product
+          }
+        }
+      }
+    }
+  }
+  ${productFragment}
+`;

lib/shopify/queries/menu.ts

@@ -0,0 +1,10 @@
+export const getMenuQuery = /* GraphQL */ `
+  query getMenu($handle: String!) {
+    menu(handle: $handle) {
+      items {
+        title
+        url
+      }
+    }
+  }
+`;

lib/shopify/queries/page.ts

@@ -0,0 +1,21 @@
+import seoFragment from '../fragments/seo';
+
+export const getPageQuery = /* GraphQL */ `
+  query getPage($handle: String!) {
+    pageByHandle(handle: $handle) {
+      id
+      ... on Page {
+        title
+        handle
+        body
+        bodySummary
+        seo {
+          ...seo
+        }
+        createdAt
+        updatedAt
+      }
+    }
+  }
+  ${seoFragment}
+`;

lib/shopify/queries/product.ts

@@ -0,0 +1,32 @@
+import productFragment from '../fragments/product';
+
+export const getProductQuery = /* GraphQL */ `
+  query getProduct($handle: String!) {
+    product(handle: $handle) {
+      ...product
+    }
+  }
+  ${productFragment}
+`;
+
+export const getProductsQuery = /* GraphQL */ `
+  query getProducts($sortKey: ProductSortKeys, $reverse: Boolean, $query: String) {
+    products(sortKey: $sortKey, reverse: $reverse, query: $query, first: 100) {
+      edges {
+        node {
+          ...product
+        }
+      }
+    }
+  }
+  ${productFragment}
+`;
+
+export const getProductRecommendationsQuery = /* GraphQL */ `
+  query getProductRecommendations($productId: ID!) {
+    productRecommendations(productId: $productId) {
+      ...product
+    }
+  }
+  ${productFragment}
+`;

lib/shopify/types.ts

@@ -0,0 +1,258 @@
+export type Maybe<T> = T | null;
+
+export type Connection<T> = {
+  edges: Array<Edge<T>>;
+};
+
+export type Edge<T> = {
+  node: T;
+};
+
+export type Cart = Omit<ShopifyCart, 'lines'> & {
+  lines: CartItem[];
+};
+
+export type CartItem = {
+  id: string;
+  quantity: number;
+  cost: {
+    totalAmount: Money;
+  };
+  merchandise: {
+    id: string;
+    title: string;
+    product: Product;
+  };
+};
+
+export type Collection = ShopifyCollection & {
+  path: string;
+};
+
+export type Image = {
+  url: string;
+  altText: string;
+  width: number;
+  height: number;
+};
+
+export type Menu = {
+  title: string;
+  path: string;
+};
+
+export type Money = {
+  amount: string;
+  currencyCode: string;
+};
+
+export type Page = {
+  id: string;
+  title: string;
+  handle: string;
+  body: string;
+  bodySummary: string;
+  seo?: SEO;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type Product = Omit<ShopifyProduct, 'variants' | 'images'> & {
+  variants: ProductVariant[];
+  images: Image[];
+};
+
+export type ProductOption = {
+  id: string;
+  name: string;
+  values: string[];
+};
+
+export type ProductVariant = {
+  id: string;
+  title: string;
+  availableForSale: boolean;
+  selectedOptions: {
+    name: string;
+    value: string;
+  }[];
+  price: Money;
+};
+
+export type SEO = {
+  title: string;
+  description: string;
+};
+
+export type ShopifyCart = {
+  id: string;
+  checkoutUrl: string;
+  cost: {
+    subtotalAmount: Money;
+    totalAmount: Money;
+    totalTaxAmount: Money;
+  };
+  lines: Connection<CartItem>;
+  totalQuantity: number;
+};
+
+export type ShopifyCollection = {
+  handle: string;
+  title: string;
+  description: string;
+  seo: SEO;
+};
+
+export type ShopifyProduct = {
+  id: string;
+  handle: string;
+  availableForSale: boolean;
+  title: string;
+  description: string;
+  descriptionHtml: string;
+  options: ProductOption[];
+  priceRange: {
+    maxVariantPrice: Money;
+    minVariantPrice: Money;
+  };
+  variants: Connection<ProductVariant>;
+  featuredImage: Image;
+  images: Connection<Image>;
+  seo: SEO;
+  tags: string[];
+};
+
+export type ShopifyCartOperation = {
+  data: {
+    cart: ShopifyCart;
+  };
+  variables: {
+    cartId: string;
+  };
+};
+
+export type ShopifyCreateCartOperation = {
+  data: { cartCreate: { cart: ShopifyCart } };
+};
+
+export type ShopifyAddToCartOperation = {
+  data: {
+    cartLinesAdd: {
+      cart: ShopifyCart;
+    };
+  };
+  variables: {
+    cartId: string;
+    lines: {
+      merchandiseId: string;
+      quantity: number;
+    }[];
+  };
+};
+
+export type ShopifyRemoveFromCartOperation = {
+  data: {
+    cartLinesRemove: {
+      cart: ShopifyCart;
+    };
+  };
+  variables: {
+    cartId: string;
+    lineIds: string[];
+  };
+};
+
+export type ShopifyUpdateCartOperation = {
+  data: {
+    cartLinesUpdate: {
+      cart: ShopifyCart;
+    };
+  };
+  variables: {
+    cartId: string;
+    lines: {
+      id: string;
+      merchandiseId: string;
+      quantity: number;
+    }[];
+  };
+};
+
+export type ShopifyCollectionOperation = {
+  data: {
+    collection: ShopifyCollection;
+  };
+  variables: {
+    handle: string;
+  };
+};
+
+export type ShopifyCollectionProductsOperation = {
+  data: {
+    collection: {
+      products: Connection<ShopifyProduct>;
+    };
+  };
+  variables: {
+    handle: string;
+    first?: number;
+  };
+};
+
+export type ShopifyCollectionsOperation = {
+  data: {
+    collections: Connection<ShopifyCollection>;
+  };
+};
+
+export type ShopifyMenuOperation = {
+  data: {
+    menu?: {
+      items: {
+        title: string;
+        url: string;
+      }[];
+    };
+  };
+  variables: {
+    handle: string;
+  };
+};
+
+export type ShopifyPageOperation = {
+  data: { pageByHandle: Page };
+  variables: { handle: string };
+};
+
+export type ShopifyPagesOperation = {
+  data: {
+    pages: Connection<Page>;
+  };
+};
+
+export type ShopifyProductOperation = {
+  data: { product: ShopifyProduct };
+  variables: {
+    handle: string;
+  };
+};
+
+export type ShopifyProductRecommendationsOperation = {
+  data: {
+    productRecommendations: ShopifyProduct[];
+  };
+  variables: {
+    productId: string;
+  };
+};
+
+export type ShopifyProductsOperation = {
+  data: {
+    products: Connection<ShopifyProduct>;
+  };
+  variables: {
+    query?: string;
+    reverse?: boolean;
+    sortKey?: string;
+  };
+};