WXT

WXT is a framework for browser extensions. Its @wxt-dev/analytics package includes a Moderok provider so you can send events to the same Moderok project without wiring @moderok/sdk by hand.

This path is optional. If you are not using WXT, follow the rest of this guide as usual.

Install

bash

npm install @wxt-dev/analytics

Register the module

In wxt.config.ts, add the analytics module:

export default defineConfig({
  modules: ["@wxt-dev/analytics/module"],
});

The module adds the storage permission to the generated manifest if it is not already there.

Configure Moderok

Put your app key in .env (see WXT’s environment-variable docs):

dotenv

WXT_MODEROK_APP_KEY=mk_your_app_key

In <srcDir>/app.config.ts, register the Moderok provider:

import { moderok } from "@wxt-dev/analytics/providers/moderok";

export default defineAppConfig({
  analytics: {
    debug: false,
    providers: [
      moderok({
        appKey: import.meta.env.WXT_MODEROK_APP_KEY,
        endpoint: import.meta.env.WXT_MODEROK_ENDPOINT, // optional override
        trackLifecycle: true,
        trackUninstalls: false,
        uninstallUrl: undefined,
        trackErrors: true,
        captureConsoleErrors: false,
      }),
    ],
  },
});

Option	Default	What it does
`appKey`	(required)	Your `mk_…` key from the Moderok app
`endpoint`	`https://api.moderok.dev/v1/events`	Override for local or self-hosted APIs
`trackLifecycle`	`true`	`__install`, `__update`, and `__daily_ping`
`trackUninstalls`	`false`	Registers an uninstall URL (same idea as the SDK)
`uninstallUrl`	-	Optional redirect after the uninstall ping
`trackErrors`	`true`	Automatic `__error` events (see below)
`captureConsoleErrors`	`false`	Mirror `console.error` into `__error` (noisy)

Send events

WXT exposes a #analytics import. Use it from the background, popup, options, content scripts, and other entry points:

import { analytics } from "#analytics";

await analytics.track("button_clicked", { surface: "popup" });
await analytics.page();

Events are delivered to the background and forwarded to Moderok (and any other providers you configured). You do not call Moderok.init() yourself when using this integration.

Note

The WXT Moderok provider is not the same bundle as @moderok/sdk. It is a separate implementation built for WXT’s provider model. The ingestion API and dashboard accept both.

Automatic error tracking (important)

Background only

The Moderok provider’s automatic __error capture runs where WXT initializes the provider: the background / service worker. WXT does not install global error listeners in popups, options, side panels, or content scripts for the provider, so uncaught errors in those contexts are not automatically reported as __error. That is a limitation of how WXT’s analytics module is scoped, not something the Moderok API can change.

trackErrors: false turns off automatic capture in the background. captureConsoleErrors: true only affects console.error in that same background context.

For the same per-context error coverage as @moderok/sdk, add the SDK to the entry files where you need it and call Moderok.init({ appKey: "…" }) there, or handle errors manually (for example chrome.runtime.sendMessage to the background).

Compared to `@moderok/sdk`

	WXT provider	`@moderok/sdk`
Setup	`app.config.ts` + `#analytics`	`Moderok.init()` per context you track from
Custom events	`analytics.track()`	`Moderok.track()`
Automatic `__error` in every UI surface	No (background only)	Yes, if you `init()` in each context
Batching / offline queue	Fire-and-forget from WXT	SDK queue + persistence

Choose WXT when you already use @wxt-dev/analytics and want Moderok alongside other providers. Choose the SDK when you want the smallest, fully controlled integration or full error coverage everywhere.

WXT ​

Install ​

Register the module ​

Configure Moderok ​

Send events ​

Automatic error tracking (important) ​

Compared to @moderok/sdk ​

See also ​