Install the Storefront SDK

@crossup/storefront is the only thing your store needs from CrossUp. It requests recommendations, reads your catalog, carries a made-up visitor and sends signals in batches, and it can’t break your page.

npm install @crossup/storefront

pnpm add @crossup/storefront

bun add @crossup/storefront

It runs in the browser and on the server, ships its types and has no dependencies. It’s published on npm: @crossup/storefront.

Create the instance

One per page. Only the key and the connection are required.

import { createStorefront } from "@crossup/storefront";

export const crossup = createStorefront({
  apiKey: "spk_…",
  connectionId: "cn_…",
});

What it does for you

The visitor: a made-up id on every request. It can be turned off, kept in memory or replaced.
The context: page, referrer, language and screen. It identifies no one.
The connection: you set it once, not on every call.
The signals: queued, batched and retried on their own.

Everything can be changed with the options, and you need none of them to get started.

The guarantees

tryGetRecommendations returns null if something fails. It never throws.
track.* never throws or waits for the network: call it without await.
A signal that fails on the network is retried on its own, with the same id.
If the engine doesn’t answer, the recommendation comes back empty with a reason, not an error.

What you will see

// The moment, the placement and the product the shopper is viewing.
const decision = await crossup.tryGetRecommendations({
  surface: "pdp",
  placementKey: "pdp-related",
  contextItemId: item.id,
});

console.log(decision?.decision_id, decision?.results.length);
// dec_… 3

If you don’t see it

What happens	What to do
`null` and no request in the Network tab	The instance is missing the key or the connection
`401` on every request	The key is miscopied or revoked. Generate another one in the admin
`403` on every request	The connection belongs to another store
`onVisitorError` on every request	The browser won’t allow storage (private mode, blocked cookies). The request still goes out, without a visitor

Request recommendations

The request, and what comes back.

Visitor and context

What travels, what doesn’t, and what to do without consent.

​Create the instance

​What it does for you

​The guarantees

​What you will see

​If you don’t see it