Docs · storefront package 4.7.1

Install guide

The storefront package is one file, installed once per storefront. After that, every test your workspace runs for the storefront's business is assigned, recorded at the payment step and credited with purchases. A new test needs no storefront change.

Three steps, once. Nothing to install from npm, no config file, no route file.

1. Add the file
Copy the package file, optimiser-storefront.ts, to lib/optimiser-storefront.ts in the storefront repository. It has no dependencies. Its header names the package version.
2. Wrap your middleware and add the health path
Keep your existing middleware as it is and wrap it with withOptimiser. Add /api/optimiser-health to the matcher.
```
import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
import { withOptimiser } from "./lib/optimiser-storefront";

function middleware(request: NextRequest, event: NextFetchEvent) {
  // Your existing middleware, unchanged.
  return NextResponse.next();
}

export default withOptimiser(middleware);

export const config = {
  matcher: ["/((?!api|_next|_vercel|.*\\..*).*)", "/api/optimiser-health"],
};
```
The matcher entry is required. Most matchers leave out /api, and the wrapper answers the health path itself. Without the entry the tool reads a 404 and records the storefront as unreachable.
The file is middleware.ts on Next 15 and below, and proxy.ts on Next 16. The wrapper is the same in both. If the storefront already runs its own assignment code or conversion ping, remove it in the same change.

3. Set the environment variables and redeploy

Two are required: OPTIMISER_URL, your workspace address, and OPTIMISER_BUSINESS, the business name exactly as your workspace spells it. A spelling mismatch drops every test. Set the optional ones your storefront needs.

OPTIMISER_URL=https://your-company.optimiser.pro
OPTIMISER_BUSINESS=Your Business
OPTIMISER_CONVERSION_PATHS=/confirmation,/thank-you
OPTIMISER_CHECKOUT_PATHS=/checkout/:order
OPTIMISER_ORDER_ID_PARAM=orderId

Redeploy, then check the health path:

curl -s https://shop.your-company.com/api/optimiser-health

{
  "business": "Your Business",
  "hosts": ["shop.your-company.com"],
  "middlewareVersion": "4.7.1",
  "toolUrlSet": true,
  "keys": ["*"],
  "handlesAllKeys": true,
  "conversionPaths": ["/confirmation", "/thank-you"],
  "checkoutPaths": ["/checkout/:order"],
  "applyParams": [],
  "assignPaths": [],
  "orderIdParam": "orderId",
  "didCookie": "optimiser_did",
  "legacyDidCookies": []
}

Every variable the install sets shows up in this answer, so one request confirms the deploy read it. The ingest key is never in it.

Environment variables

With OPTIMISER_URL unset, the wrapper hands every request to your own middleware and does nothing else.

OPTIMISER_URLrequired: Your workspace address, for example https://your-company.optimiser.pro. A trailing slash is removed.
OPTIMISER_BUSINESSrequired: The business name exactly as your workspace spells it. Tests for any other business are dropped, so a spelling mismatch drops every test.
OPTIMISER_INGEST_KEYdefault: unset: Sent with every event. Set it only when your workspace has an ingest key, to the same value.
OPTIMISER_HOSTSdefault: every host: Comma-separated host names the package runs on. Needed when one repository serves several sites.
OPTIMISER_KEYSdefault: every test: Comma-separated test keys to limit the package to. Leave unset unless there is a reason.
OPTIMISER_ASSIGN_PATHSdefault: every path: Comma-separated paths that enrol a visitor, written without the locale. Purchases are recorded on any path.
OPTIMISER_DID_COOKIEdefault: optimiser_did: The cookie that holds the visitor id.
OPTIMISER_LEGACY_DID_COOKIESdefault: none: Comma-separated old visitor-id cookies to move visitors from. Read first, so nobody changes id or arm.
OPTIMISER_APPLY_PARAMSdefault: none: Comma-separated URL parameters your storefront renders, for example var. A listed parameter's arm is applied by redirect.
OPTIMISER_CONVERSION_PATHSdefault: /thank-you: Comma-separated success pages, written without the locale. Each one records a purchase.
OPTIMISER_CHECKOUT_PATHSdefault: unset: off: Comma-separated payment pages. Each one records a checkout with the order id. A segment written :order holds the id, for example /checkout/:order.
OPTIMISER_ORDER_ID_PARAMdefault: unset: The URL parameter that holds the order id. Set it, so each order is recorded once.
OPTIMISER_CURRENCY_PARAMdefault: currency: The success-page URL parameter that holds the ISO currency.
OPTIMISER_DECIDE_TIMEOUT_MSdefault: 500: The longest the page waits for an assignment, in milliseconds.

Questions about an install: email reach@optimiser.pro. No workspace yet: ask for one.

Install guide

1. Add the file

2. Wrap your middleware and add the health path

3. Set the environment variables and redeploy

Environment variables