Skip to main content

Overview

Integration packages are designed for High Velocity Next.js apps and provide vendor agnostic interfaces to various integrations, such as:

  • Commerce
  • Cms
  • Search
  • OMS

This interface includes functions for server side data fetching and mutation, client side hooks, and ui components.

Anatomy of an Integration Package​

Integration packages share a common structure. This ensures a consistent and predictable developer experience.

Models​

Models are zod schemas and type definitions used by a particular integration type.

You will find these under the /models sub-export for each integration package.

import type { Product } from '@hv/commerce/models';

Models are vendor agnostic. They are the contract between integrations and the app.

Integration Functions​

These factory functions instantiate an integration and return functions for interacting with it. Factory functions are named with PascalCase and are intended to be used in server components and route handlers. They are not available in client components

Usage​

In a route handler or server component, you need only pass an object containing information about the current app context, such as the current locale:

const { getCategoryByHandle } = Catalog({
  locale: 'en-US',
});

const categoryResult = await getCategoryByHandle('clothing');

Hooks​

For client components, each integration package exposes hooks that can be used for client side fetches and mutations.

For example, here are some hooks that the commerce package exports:

  • useCart()
  • useProduct()
  • useAddToCart()

Usage​

To use integration package hooks, import them from the /client sub-export:

"use client";

import { useCart } from '@hv/commerce/client';


export function CartComponent() {
  const { cart } = useCart();

  return (
    ...
  )
}

Remember, you must be inside of a client component to use hooks ("use client").

UI​

UI Components are reusable react ui components which use the integration package models.

Usage​

You will find these exported from the package with the /ui prefix.

To preserve the option to be dynamically imported and to minimize bundle size, ui components are logically grouped and exported. Putting all of these elements together, the beginnings of a cart route might look something like this:

import { notFound } from 'next/navigation';
import { Cart, getSessionHandler } from '@hv/commerce';
import { Pricing } from '@hv/commerce/ui/pricing';
import { Heading } from '@hv/ui/typography';


export default async function CartRoute({ params }: { params: { locale: string }}) {
  const serverContext = {
    locale: params.locale
  };

  const sessionHandler = getSessionHandler(serverContext);
  const session = await sessionHandler.getSession();

  const { getCart } = Cart({
    ...serverContext,
    session
  });

  const cartResult = await getCart();
  if (!cartResult.success) {
    return notFound();
  }

  const cart = cartResult.object;

  return (
    <>
      <Heading>My Cart ({cart.itemCount} items)</Heading>
      <Pricing price={cart.total}>
    </>
  )
}