NPM package (@metricraven/web)

@metricraven/web loads the MetricRaven tracker for you and gives you typed functions to call it. It has no dependencies and is safe to import during server rendering.

The package loads the same hosted script as the HTML tag, with the options you pass. So consent rules, single-page app routing and the data it sends are the same either way. Use the package or the tag, not both. If the tag is already on the page, the package uses it instead of loading a second copy.

Install

1. Add the package

   terminal

   Copy

   1

   npm install @metricraven/web

2. Call init once, in the browser

   Call init from client code that runs once, such as a root layout effect. Calling it again does nothing. On the server, every function does nothing.

   Next.js App Router

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   // app/analytics.tsx
   "use client";
   import { useEffect } from "react";
   import { init } from "@metricraven/web";
   
   export function Analytics() {
     useEffect(() => {
       init({ siteId: process.env.NEXT_PUBLIC_METRICRAVEN_SITE_ID! });
     }, []);
     return null;
   }
   
   // app/layout.tsx: render <Analytics /> once inside <body>.

3. Track events and identify users

   You can import these anywhere, even before init. Calls made before the script loads are queued and sent in order.

   server.ts

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   import { track, identify, pageview, setConsent, reset, getVisitorId } from "@metricraven/web";
   
   track("checkout_started", { plan: "pro" });
   identify(user.id, { name: user.name, email: user.email, plan: "pro" });
   pageview("/checkout/payment"); // a virtual screen; with autoPageviews: false, every view
   setConsent(true); // from your cookie banner
   reset(); // on logout
   const visitorId = getVisitorId(); // null until the first response

Options

init({
  siteId: "YOUR_SITE_ID",
  apiHost: "https://metricraven.com", // where MetricRaven is served
  scriptUrl: "/a/script",              // or: a same-origin proxy path for the script…
  endpoint: "/a/event",                // …and for events
  autoPageviews: true,                 // false: call pageview() yourself
  hashRouting: false,                  // true: count #/route paths; "all": also #anchors
  stripQuery: false,
  consent: false,                      // true when your banner already has consent
  domain: "example.com",               // share the consented cookie across subdomains
  allowedHostnames: ["app.example.io"], // your other domains: keep the same visitor across them
  allowLocalhost: false,
  debug: false,                        // true: log what is sent to the console
});

Functions

Other frameworks

// main.ts (Vue / Nuxt client plugin)
import { init } from "@metricraven/web";
init({ siteId: import.meta.env.VITE_METRICRAVEN_SITE_ID });

<!-- src/routes/+layout.svelte -->
<script>
  import { onMount } from "svelte";
  import { init } from "@metricraven/web";
  onMount(() => init({ siteId: import.meta.env.PUBLIC_METRICRAVEN_SITE_ID }));
</script>
<slot />

• React (Vite): call init in main.tsx before rendering.
• Routers that use the history API are tracked automatically. For hash routers, pass hashRouting: true. See SPA & virtual pages.
• Landing site and app on different domains? Pass allowedHostnames and use linkUrl for navigation in code. See Cross-domain tracking.