Releases

A release is the label that turns “the site got slower” into “the site got slower on Tuesday’s deploy”. Without one, every measurement blurs into a single undifferentiated population and a regression has no cause you can point at.

Declaring one

npm

Pass it to init():

import { init } from '@ritim/browser-sdk';

init({
  projectKey: 'P-ABC123',
  release: RELEASE,
});

Where RELEASE comes from is your framework’s business rather than ours: it has to be a value your build puts into the client bundle, and each framework has its own mechanism and its own naming rules for that. Both guides cover it, with links to the official documentation: Next.js · Nuxt.

Often you do not need this at all. Both frameworks have a config option that publishes a build identifier the SDK reads on its own — one line in next.config.ts or nuxt.config.ts and nothing reaches your application code.

If you only learn the value after startup, set it later instead:

import { setRelease } from '@ritim/browser-sdk';

setRelease(buildId);

setRelease applies to subsequent measurements, not to ones already sent, so call it as early as you can.

Script tag

On the tag:

<script
  async
  src="https://cdn.ritim.io/latest/browser.min.js"
  data-project-key="P-ABC123"
  data-release="a1b2c3d"
></script>

From the head, which wins over data-release — so a page that already renders its build id into the head does not have to template the script tag as well:

<meta name="rum-release" content="a1b2c3d" />

At runtime, for a value you only learn after load:

window.RumMonitor.setRelease(buildId);

Full precedence

1. init({ release })
2. <meta name="rum-release">
3. data-release on the script tag
4. the framework’s own build identifier
5. a fingerprint of the page’s assets

The first three are what you say. The last two are what the page can be asked, and both are resolved when a measurement is sent rather than at startup — the globals one reads do not exist until the framework hydrates, and the assets the other reads have not all loaded.

When you declare nothing

Some frameworks publish a build identifier of their own, and the SDK reads it. Where that happens you get one release per deploy having configured nothing at all — and where it does not, one line of framework config is usually enough to fix it at the source, without touching your application code.

Which case you are in depends on the framework and sometimes on how it is deployed, so it is covered on the page for each:

Next.js releasesWhat is detected, when it is not, and what to pass instead.

Nuxt releasesWhat is detected, and how to pin it to a value you choose.

Anything you declare overrides detection, on every framework.

The asset fingerprint

Failing all of the above, the SDK hashes the URLs of the first three same-origin scripts and first three stylesheets, in document order. Build tooling puts a content hash in those filenames, so the set changes when a deploy changes.

It is reported with a ~ prefix — ~1dwgo1a — because a value inferred from filenames and a version someone chose are not the same kind of claim, and the dashboard should not have to explain which is which.

A signal, not an identifier

• It cannot name a version, only tell you the version changed. - Under route-level code splitting, two pages of one deploy can fingerprint differently. Taking assets in document order softens this — the first few scripts are usually the shared runtime and vendor chunks — but does not fix it. - Cross-origin assets are excluded. A third-party script ships on somebody else’s schedule, and including one would invent a release every time it did.

This tier is what a plain HTML page or an unrecognised framework gets.

What to declare

One stable value per deploy. A commit SHA is the obvious choice and the one most CI systems hand you for free.

How that value reaches your build is a question about your CI and your host, not about this SDK — every platform exposes the commit under its own variable name, and both framework guides link to the official documentation for reading it.

Avoid anything that changes without the code changing — a timestamp, or a per-request value. Each distinct release is its own population in the dashboard, and a release that is unique per page view is a release with a sample size of one.