Install with WXT

WXT builds the manifest, the background and every extension page for you, for Chrome and Firefox from one project. AnalyticsTrend fits in two ways:

• With WXT's analytics module. @analyticstrend/wxt-analytics is a provider for it. Call analytics.track from any page, popup or content script, and turn analytics on or off with WXT's own switch.
• Directly. Call the extension SDK yourself, inside defineBackground.

Both keep what the SDK guarantees: events survive a suspended background, Firefox's data-collection choice is honoured, and uninstalls can be recorded.

Start from the template

npx giget@latest gh:deasil-org/analytics-trend-integrations/templates/wxt my-extension
cd my-extension
cp .env.example .env
npm install

Put your write key in .env, then npm run dev. The template uses the analytics module, and its popup has a "Share anonymous usage" switch.

With WXT's analytics module

npm install @analyticstrend/wxt-analytics @analyticstrend/extension @wxt-dev/analytics@0.5.4

Use @wxt-dev/analytics 0.5.4 with npm

0.5.5 and 0.5.6 publish a development postinstall script that fails under npm, so the install stops. pnpm skips dependency install scripts and works with any of them.

Add the module, and the Firefox block, in wxt.config.ts:

import { defineConfig } from "wxt";

export default defineConfig({
  modules: ["@wxt-dev/analytics/module"],
  manifest: ({ browser }) => ({
    permissions: ["storage"],
    ...(browser === "firefox" && {
      browser_specific_settings: {
        gecko: {
          id: "your-extension@example.com",
          strict_min_version: "140.0",
          data_collection_permissions: {
            required: ["none"],
            optional: ["technicalAndInteraction", "locationInfo"],
          },
        },
      },
    }),
  }),
});

Then the provider, in app.config.ts:

import { analyticsTrend } from "@analyticstrend/wxt-analytics";

export default defineAppConfig({
  analytics: {
    enabled: storage.defineItem<boolean>("local:analytics-enabled", { fallback: true }),
    providers: [
      analyticsTrend({ writeKey: import.meta.env.WXT_ANALYTICSTREND_WRITE_KEY, uninstallTracking: true }),
    ],
  },
});

WXT's switch is off by default, so name an enabled item as above, or call analytics.setEnabled(true) once the person agrees. Either way the provider follows it: while it is off nothing is sent or stored, and the uninstall link is cleared.

Send events from anywhere:

import { analytics } from "#analytics";

analytics.track("popup_opened");

What reaches AnalyticsTrend

WXT's module attaches more to each event than AnalyticsTrend collects. The provider drops it.

WXT hands the provider	What happens
track: the event name and properties	Sent as the event and its properties
An auto-tracked click: tag, id, class	Sent
An auto-tracked click: text and link	Dropped. On a website they are that site's content and a full address
page(url)	page_viewed, with path only for the extension's own pages; a website page gets no path
identify: a user id and properties	Ignored. The SDK keeps its own random identifier
Language, screen, referrer, address, title, session, browser version	Never sent

Event names follow the naming rules: lowercase letters, digits and underscores. A name that breaks them is dropped.

Directly, without the module

// entrypoints/background.ts
import { initBackground } from "@analyticstrend/extension";

export default defineBackground(() => {
  const analytics = initBackground({
    writeKey: import.meta.env.WXT_ANALYTICSTREND_WRITE_KEY,
    uninstallTracking: true,
  });
  analytics.track("background_started");
});

Inside main(), never at the top level

WXT imports the background file in Node during the build, to read its options. Code at its top level runs then, in Node, not in the browser. main() runs on every background start, and it cannot be async, which suits initBackground: it must not be awaited anyway.

From a popup or content script, use trackFromContentScript, as in the Chrome guide. The direct example does both.

Build for each store

wxt build                  # Chrome, in .output/chrome-mv3
wxt build -b firefox --mv3 # Firefox, in .output/firefox-mv3

WXT builds Firefox as Manifest V2 unless told otherwise. --mv3 matches the rest of these guides. The store disclosure helper gives the Chrome Web Store answers and the Firefox block, and the store policy page explains them.