Installation

There are two ways to load the library, depending on whether your site has a build step:

• From npm — if you have a bundler. You get types, tree-shaking, and version pinning through your lockfile.
• From a CDN — for sites without a build step (tag managers, server-rendered templates, plain HTML). A plain <script> tag, nothing to install.

Pick one — the usage past load() is identical either way.

From npm (recommended)

Remove the standard Segment package and replace it with this wrapper:

bun remove @segment/analytics-next
bun add @adpharm/silo-analytics

Peer dependency

@segment/analytics-next is a peer dependency of @adpharm/silo-analytics. Removing your direct install is fine — your package manager keeps it present transitively. You import everything from @adpharm/silo-analytics instead: it re-exports the full analytics-next surface unchanged — runtime exports and TypeScript types — so any existing import { ... } from "@segment/analytics-next" (including import type) becomes import { ... } from "@adpharm/silo-analytics" with no other changes.

// before
import { AnalyticsBrowser } from "@segment/analytics-next";

// after — same surface, plus the Time on Page plugin auto-registers
import { AnalyticsBrowser } from "@adpharm/silo-analytics";

From a CDN (no build step)

For sites without a bundler you can load silo-analytics straight from the CDN. Two self-contained bundles are published per release (Segment is bundled in — nothing else to load):

File	Format	Use with
silo-analytics.min.js	IIFE, global SiloAnalytics	classic <script src>
silo-analytics.esm.js	ESM	<script type="module">

Classic script tag (global)

silo-analytics.min.js attaches everything to a window.SiloAnalytics global, mirroring the @adpharm/silo-analytics module surface:

<script src="https://cdn.silo.adpharm.digital/lib/v2.2.1/silo-analytics.min.js"></script>
<script>
const analytics = SiloAnalytics.AnalyticsBrowser.load({
  writeKey: "YOUR_WRITE_KEY",
  env: "production",
});
analytics.ready(() => analytics.page());
</script>

ES module

silo-analytics.esm.js is a standard module — import the same named exports you would from the npm package:

<script type="module">
import { AnalyticsBrowser } from "https://cdn.silo.adpharm.digital/lib/v2.2.1/silo-analytics.esm.js";

const analytics = AnalyticsBrowser.load({
  writeKey: "YOUR_WRITE_KEY",
  env: "production",
});
analytics.ready(() => analytics.page());
</script>

Everything past load() is identical to the npm usage — see Quick Start for env, the initial page view, and SPA route changes, and Configuration for every option.

One bundle serves every writeKey

The bundle is the same for all sources — the writeKey is a runtime argument to load(), not baked into the file. load() fetches that writeKey’s settings from cdn.silo.adpharm.digital/v1/projects/<writeKey>/settings at runtime (see Remote Settings). There is no per-writeKey bundle to build or host.

Versioning

Each release publishes to two paths:

• Pinned (recommended): …/lib/v2.2.1/silo-analytics.min.js — an exact version. The bytes at a pinned URL never change, so it’s safe to cache hard. Use this in production so a new release can’t change behavior under you.
• Major alias: …/lib/v2/silo-analytics.min.js — tracks the latest release within major v2. Convenient for “always get the newest patch,” but updates propagate on the CDN’s cache TTL (not instantly to browsers that already cached it), and a future patch can change behavior without a URL change.

Pin a version in production

Pin the full vX.Y.Z URL for anything customer-facing. Reserve the vMAJOR alias for quick experiments where auto-updating is worth the loss of determinism.

The snippets above pin v2.2.1 — the current release (the CDN version matches the npm version). Bump to a newer pinned version as you upgrade.

Requirements

• A browser runtime. The library is browser-only ESM; analytics only runs in the browser.
• A Segment-compatible tracking endpoint (defaults to the Silo event gateway — see Configuration to override).

SSR / server rendering

Safe to import and call AnalyticsBrowser.load(...) from a module that your framework also evaluates server-side (Astro, Next, etc.). load() detects the absence of window and no-ops on the server, then boots normally on the browser — so you don’t need to guard the call yourself or split the import. (Underlying @segment/analytics-next is browser-only and throws window is not defined if loaded server-side; the wrapper absorbs that.)

Next: Quick Start.