UXSense

Setting up Drift

Drift checks every pull request and warns you before a change breaks something your users rely on. It works in three levels. Each level catches more, and each one takes a little more setup. You can stop at any level.

In a hurry? Run npx @uxsense/wizard in your repo. It writes a file called UXSENSE-SETUP.md with every step below, ready to hand to your coding agent. Nothing is changed until you say so.

Level 1 — Record sessions

What you get: a map of what your users actually do, which is the ground truth every check is scored against.

What to do: connect one session source. The recorder snippet is one script tag. Or connect PostHog if you already use it. Then wait for about 30 recorded sessions. The map builds itself and keeps updating.

How to know it worked: the Drift page shows a session count that climbs, and "Load map computed" gets a tick at 30.

If the count stays at zero: open your live site, view the page source, and look for app.uxsense.ai/api/r.js. If it isn't there, the snippet is in your config but not in the build that's live. Redeploy.

Level 2 — Tell Drift what changed in each pull request

What you get: Drift can see when a pull request removes, renames, or reworks a component that real users depend on. Without this level, every check runs in "limited" mode and says so.

What to do: three small changes to your repo. About ten minutes.

  1. Add the build plugin, which labels each component during your build.

    npm install --save-dev @uxsense/stamp

    Then enable it for your framework. The @uxsense/stamp readme has the exact snippet for Next.js and Vite.

  2. Copy your project's API key from Settings into your CI provider's secrets as UXSENSE_API_KEY.

  3. Add one upload step to the workflow that already builds your pull requests and your main branch:

    - name: Upload behavioral manifest
  env:
    UXSENSE_API_KEY: ${{ secrets.UXSENSE_API_KEY }}
  run: npx uxsense upload-manifest

How to know it worked: open a pull request. You'll see two checks. The first posts within seconds and says "Limited check — no build manifest for this commit". Once your build finishes and uploads, a second full check replaces it. Two checks is normal, not a glitch.

Heads-up for Next.js: the plugin runs through Babel, so adding a .babelrc switches Next.js from its default compiler to Babel. Builds get a bit slower. The readme lists two extra lines that avoid confusing build errors when you make that switch.

Level 3 — Let Drift click through a preview

What you get: Drift replays real user journeys against a preview of the pull request. This is the only level that catches something that still exists in the code but a person can no longer reach, like a button hidden behind a banner or pushed off screen. A CSS-only change looks clean to Level 2 and gets caught here.

What to do: have a preview deployment for each pull request. Vercel, Render previews, Netlify, and Amplify are picked up automatically. For anything else, set a URL pattern under Connections, then Path replay previews.

If your users' journeys go through a form, such as login or search, add test values under the same Connections panel so the replay can get past it. Fields are matched by their label. A dropdown value must match one of its options exactly.

How to know it worked: the PR check shows "replay" with a count of verified journeys.

Without previews: you keep Levels 1 and 2. Breakage of this kind still gets caught, but after the deploy, in your next impact report.

If a check looks wrong

The check keeps saying "Limited check" after CI finished. The upload step isn't running or UXSENSE_API_KEY isn't set in CI. Check the CI log for a line starting with Uploaded.

CI says "UXSENSE_API_KEY is not set". The secret is missing from your CI provider. Add it.

CI says "Uploaded … stamps for" a commit that isn't the pull request's latest commit. You're on an old version of @uxsense/stamp. Run npm install @uxsense/stamp@latest and commit the updated lockfile. CI installs exactly what the lockfile says.

A CSS-only change reads clean. Expected at Level 2. Only Level 3 can see it.

Sessions aren't arriving. See Level 1.

A replay says "unverified". The journey couldn't get past a form. Add test values under Connections.

A note on the dry-run tool

The check_drift tool in your coding agent is a quick pre-flight, not the real verdict. It's deliberately cautious and may warn where the pull request check comes back clean, and it can't see renames. Use it to catch risky edits before you commit. Trust the PR check for the answer.

← All help articles