Upgrading to @pack/hydrogen 5.0

For storefronts on @pack/hydrogen 4.x. On 3.x? Make the theme changes in Upgrading to @pack/hydrogen 4.0 first. You can then install 5.x directly.

@pack/hydrogen 5.0 lets A/B tests that change different content reach the same visitor, even on the same page. It also lets your own experimentation tool assign visitors while Pack serves the content. Most storefronts need no code changes. This guide covers what changes and what to check, including the cookie changes in 5.0.1 and 5.1.0.

Before you upgrade

Upgrade between tests, not during one. On 4.x, two tests that change the same kind of content (both change pages, say) split visitors between them. On 5.0 they both reach the same visitor when they change different content. A visitor split between two tests before the upgrade can be in both after it, so visitors from before and after the upgrade are no longer comparable. Existing assignments are kept, but the result of a test already in flight is affected.

The best time to upgrade is when no test is running, or right after one ends.

Install

package.json

{
  "dependencies": {
    "@pack/hydrogen": "^5.1.0",
    "@pack/react": "^4.6.0"
  }
}

Requirements are unchanged from 4.x: React Router 7, @shopify/hydrogen ^2026.1.0 and Node 20 or later. See Requirements.

What changes for your visitors

  • Tests that change different content serve together. Two tests that change different sections of one page, or different site settings, both reach the visitor and both apply. Up to three tests can apply to one query.
  • Tests that change the same content still split visitors. Which test a visitor gets stays fixed per visitor, as in 4.x.
  • Personalizations behave as in 4.x. A personalization is still shown instead of an A/B test that changes the same kind of content.

Pack compares tests by the content they change:

  • Sections. A test that edits a section changes that whole section. Two tests editing different sections can run together; two editing the same section split visitors.
  • Site settings. A test changes only the settings it edits, so a cart upsell test and a header test can run together.
  • Page layout. A test that adds, removes or swaps sections, or changes the page's template, changes every section it shows or hides. Reordering sections alone doesn't count.

When you start a test, the start dialog in Pack lists the running tests it will run alongside and those it will split visitors with.

Theme changes

Most storefronts need none. Exposure reporting already handles several tests per page: since 4.0, PackTestRoute reports one exposure per test that serves.

If your storefront assigns tests itself

Some storefronts assign visitors with their own experimentation tool and pass the result to Pack by adding test_handle and test_variant_handle to the request URL, or by wrapping queries in a test option. On 5.0, pass the assignments to createPackClient instead:

  1. Pass every assignment for the request as externalTestAssignments. Pack serves each on the queries it changes, and stacks tests that change different content.
  2. Stop adding test parameters to the request URL. A test URL parameter outranks externalTestAssignments.
  3. Remove any test: {} option used to stop Pack assigning visitors. It also stops external assignments on that query, and externalTestAssignments already turns Pack's assignment off.
  4. Report exposures from pack.abTests (or useAbTests()), which can hold several tests, rather than pack.abTest.

See Using Your Own Testing Tool.

If you cache Pack responses yourself

pack.query handles this for you. If you call the Pack API through your own cache or proxy, note that a query serving two or three tests sends X-Pack-Test-Variant-Ids and X-Pack-Published-At instead of the single-test headers. Include both in your cache key.

These patch and minor releases tighten Pack's cookies. They matter only if your theme reads Pack's cookies directly, or constructs PackSession itself.

  • 5.0.1: __pack and __pack_s are HttpOnly, so scripts on the page, including third-party tags, can no longer read them. To use the Pack visitor id, read context.pack.session.id on the server and pass it down.
  • 5.1.0: preview state moves to its own cookie, __pack_preview, so __pack and __pack_s can be SameSite=Lax. pack.session.get() and set() still read and write the preview keys, so theme code needs no change. Anyone previewing at the moment you deploy sees the live site until the editor reloads or the preview link is opened again.
  • 5.1.0: constructing new PackSession() with six arguments is deprecated. It still works, but keeps preview state in __pack under your cookie settings. Use PackSession.init().

See Pack's cookies.

Checking the upgrade

  • Run two tests that change different sections of the same page. A visitor in both should see both changes, and window.packDebug.getTestInfos() should list both.
  • Your analytics should receive one exposure per test the visitor sees on a page.
  • Preview a page from the Customizer and check that the preview bar and draft content still appear.
  • If your storefront assigns tests itself, check that useAbTests() lists every assignment you passed. See Debugging.

Was this page helpful?