Shopify Hydrogen / Remix

Environment Variables

Add the following to your .env file:

INTELLIGEMS_ORG_ID=<Intelligems-ID>
SHOPIFY_STOREFRONT_ACCESS_TOKEN=<Storefront-API-Token>

Vite Configuration

Add the intelligemsVitePlugin to your vite.config.ts plugins array. This plugin is required for the Intelligems Preview Mode widget to render and function correctly in Hydrogen apps. This plugin should be placed at the end / near the end of the plugins array, after the hydrogen and oxygen plugins.

Why is this needed?

The oxygen() Vite plugin from @shopify/mini-oxygen sets resolve.conditions to ["worker", "workerd"] globally, which causes client-side dependencies like @emotion/* and @mui/* to resolve server/edge build variants instead of browser builds. This breaks CSS injection and component interactivity in the Preview Mode widget.

The intelligemsVitePlugin moves these conditions to ssr.resolve.conditions where they belong, so that only server-side code uses worker builds while client-side code correctly resolves browser builds.

Is this safe?

The plugin has zero runtime cost — it runs once during Vite config resolution. Client-side code runs in the browser, not in a worker, so it should never have worker conditions applied. SSR behavior is completely unaffected since the worker conditions are preserved under ssr.resolve.conditions.

import { defineConfig } from "vite";
import { hydrogen } from "@shopify/hydrogen/vite";
import { oxygen } from "@shopify/mini-oxygen/vite";
import { vitePlugin as remix } from "@remix-run/dev";
import { intelligemsVitePlugin } from "@intelligems/headless/hydrogen";

export default defineConfig({
  plugins: [
    hydrogen(),
    oxygen(),
    remix({
      presets: [hydrogen.preset()],
      future: {
        v3_fetcherPersist: true,
        v3_relativeSplatPath: true,
        v3_throwAbortReason: true,
        v3_lazyRouteDiscovery: true,
      },
    }),
    tsconfigPaths(),
    intelligemsVitePlugin(),
  ],
  ssr: {
    optimizeDeps: {
      include: ["@intelligems/headless/hydrogen"],
    },
  },
});

loader() Configuration

Update the loader() function to pre-load the Intelligems configuration. Optionally pass in a cache interval (in minutes).

import {
  getIntelligemsConfig,
} from '@intelligems/headless/hydrogen';

export async function loader({request, context}: LoaderFunctionArgs) {
  ...
  const intelligems = await getIntelligemsConfig(env.INTELLIGEMS_ORG_ID, CACHE_INTERVAL_IN_MINUTES);
  
  return {
    ...
    intelligems,
  }
}

Provider Integration

The IntelligemsHydrogenProvider component stores Intelligems data in React Context so hooks and components can access it throughout your app.

import { IntelligemsHydrogenProvider } from "@intelligems/headless/hydrogen";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      <IntelligemsHydrogenProvider
        config={intelligems} // Optional: returned from your loader response
        organizationId={process.env.INTELLIGEMS_ORG_ID}
        storefrontApiToken={process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN}
        activeCurrencyCode="USD" // Must be provided
        antiFlicker={true}
      >
        ...
      </IntelligemsHydrogenProvider>
    </>
  );
}

Page Views Tracking

useIgTrack is a client-side hook tracking page views.

To provide accurate analytics ensure it is configured with valid parameters:

• cartOrCheckoutToken

• currency

• country

import {
  IntelligemsHydrogenProvider,
  useIgTrack,
} from "@intelligems/headless/hydrogen";
import { ClientOnly } from "remix-utils/client-only";

const IntelligemsTracker = ({
  cartOrCheckoutToken,
  currency,
  country,
}: {
  cartOrCheckoutToken: string | undefined | null;
  currency: string | undefined | null;
  country: string | undefined | null;
}) => {
  useIgTrack({
    cartOrCheckoutToken,
    currency,
    country,
  });
  return null;
};

export default function App({ children }) {
  return (
    <IntelligemsHydrogenProvider
      organizationId={process.env.INTELLIGEMS_ORG_ID}
      storefrontApiToken={process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN}
      antiFlicker={true}
    >
      <StoreProvider>
        <ClientOnly>
          {() => (
            <IntelligemsTracker
              cartOrCheckoutToken={...}
              country={...}
              currency={...}
            />
          )}
        </ClientOnly>
        {children}
      </StoreProvider>
    </IntelligemsHydrogenProvider>
  );
}