npm package: @hellyeah/x-ray
Description: Multi-platform analytics SDK for browser, React, Next.js, Remix, Vue, Svelte, Nuxt, Astro, and server environments
Latest version: 0.1.2

![X-Ray Analytics](https://3ru7zisrfyqqm8y4.public.blob.vercel-storage.com/banner.webp)

<div align="center">
  <strong>X-Ray Analytics SDK</strong>
  <br />
  <p>Privacy-friendly analytics for web and server applications</p>
  <a href="https://www.npmjs.com/package/@hellyeah/x-ray"><img src="https://img.shields.io/npm/v/@hellyeah/x-ray.svg" alt="npm version" /></a>
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license: MIT" />
</div>

## Overview

`@hellyeah/x-ray` allows you to track page views, custom events, and user identity across any JavaScript framework or server environment.

All page views are automatically tracked by default. Custom events and user identification are available via a simple API.

## Quickstart

1. Install the package

   ```bash
   npm install @hellyeah/x-ray
   ```

2. Add analytics to your app

   **Next.js**

   ```tsx
   import { Analytics } from "@hellyeah/x-ray/next";

   export default function RootLayout({ children }) {
     return (
       <html>
         <body>
           {children}
           <Analytics websiteId="your-website-id" />
         </body>
       </html>
     );
   }
   ```

   **React**

   ```tsx
   import { Analytics } from "@hellyeah/x-ray/react";

   function App() {
     return (
       <>
         <Analytics websiteId="your-website-id" />
         {/* your app */}
       </>
     );
   }
   ```

   **Vue / Nuxt / Svelte / Remix / Astro** — see [Framework Guides](#frameworks) below.

   **Vanilla JS**

   ```ts
   import { inject } from "@hellyeah/x-ray";

   inject({ websiteId: "your-website-id" });
   ```

   **Server (Node.js / Bun)**

   ```ts
   import { XRay } from "@hellyeah/x-ray/server";

   const xray = new XRay("your-website-id");
   xray.track("signup", { distinctId: "user_42" });

   // Before process exit, flush remaining events
   await xray.shutdown();
   ```

   **Serverless / Edge (Vercel, AWS Lambda, Cloudflare Workers)**

   In short-lived environments, set `flushAt: 1` and `flushInterval: 0` so events are sent immediately rather than batched:

   ```ts
   import { XRay } from "@hellyeah/x-ray/server";

   const xray = new XRay("your-website-id", {
     flushAt: 1,
     flushInterval: 0,
   });

   xray.track("signup", { distinctId: "user_42" });
   ```

   Or use `trackImmediate` to bypass the queue entirely and await delivery:

   ```ts
   await xray.trackImmediate("signup", { distinctId: "user_42" });
   ```

3. Deploy your app and see data flowing in.

## Frameworks

| Framework | Import path              | Usage                                                 |
| --------- | ------------------------ | ----------------------------------------------------- |
| Next.js   | `@hellyeah/x-ray/next`   | `<Analytics />` component with Suspense boundary      |
| React     | `@hellyeah/x-ray/react`  | `<Analytics />` component                             |
| Remix     | `@hellyeah/x-ray/remix`  | `<Analytics />` component                             |
| Vue       | `@hellyeah/x-ray/vue`    | `<Analytics />` component                             |
| Svelte    | `@hellyeah/x-ray/svelte` | `injectAnalytics()` helper                            |
| Nuxt      | `@hellyeah/x-ray/nuxt`   | `injectAnalytics()` + `<Analytics />`                 |
| Astro     | `@hellyeah/x-ray/astro`  | Re-exports `inject` and `track`                       |
| Server    | `@hellyeah/x-ray/server` | `XRay` class with batching, retry, and immediate send |
| Vanilla   | `@hellyeah/x-ray`        | `inject()`, `track()`, `identify()`, `pageview()`     |

## Custom Events

```ts
import { track } from "@hellyeah/x-ray";

track("signup", { plan: "pro" });
```

For the full list of predefined conversion events and ad platform mappings, see the [Event Catalog](../../skills/references/event-catalog.md).

## User Identification

```ts
import { identify } from "@hellyeah/x-ray";

identify("user_42", { name: "Jane" });
```

## License

[MIT](LICENSE)