@metricraven/nuxt 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MetricRaven
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,100 @@
1
- # Temporary Holding Version
1
+ # @metricraven/nuxt
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The [Nuxt](https://nuxt.com) module for [MetricRaven](https://metricraven.com): privacy-friendly web analytics that shows which traffic actually pays. It adds the MetricRaven tracker to every page of your app, with no `app.vue` or `app.head` to edit.
4
+
5
+ - One entry in `nuxt.config`; works with SSR, prerendered (`nuxt generate`) and SPA (`ssr: false`) apps, on Nuxt 3.7+ and 4.
6
+ - Every option can be set per environment at runtime with `NUXT_PUBLIC_METRICRAVEN_*` variables, so staging and production can use different sites without a rebuild.
7
+ - The same hosted tracker as the `<script>` tag, with the same options. Every route change counts as a pageview.
8
+ - An auto-imported `useMetricRaven()` for goals, identify and payments from your own code.
9
+ - Adds nothing, and logs a warning at build time, when no site ID is set.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npx nuxi module add @metricraven/nuxt
15
+ ```
16
+
17
+ This installs the package and adds it to `modules` in `nuxt.config`. To do it by hand, run `npm install @metricraven/nuxt` and add it yourself:
18
+
19
+ ```ts
20
+ // nuxt.config.ts
21
+ export default defineNuxtConfig({
22
+ modules: ["@metricraven/nuxt"],
23
+ metricraven: {
24
+ siteId: "ana_pub_…", // Settings → Tracking & install in MetricRaven
25
+ },
26
+ });
27
+ ```
28
+
29
+ Or leave `siteId` out and set the `NUXT_PUBLIC_METRICRAVEN_SITE_ID` environment variable where the app runs. Nuxt reads it at runtime, so one build can serve several environments.
30
+
31
+ Deploy and open your site. `nuxt dev` runs on `localhost`, which is not tracked unless you set `allowLocalhost: true` and add `localhost` to your site's domains.
32
+
33
+ Remove the `<script src="https://metricraven.com/js/script.js">` tag from `app.head` or `app.vue` if you had one, so the tracker isn't added twice.
34
+
35
+ ## Options
36
+
37
+ | Option | Default | |
38
+ | --- | --- | --- |
39
+ | `siteId` | `NUXT_PUBLIC_METRICRAVEN_SITE_ID` | Your site ID from Settings. Without one, nothing is added |
40
+ | `apiHost` | `https://metricraven.com` | Where MetricRaven is served |
41
+ | `scriptUrl` | `<apiHost>/js/script.js` | The tracker URL, e.g. a same-origin proxy path such as `"/a/script"` ([proxy with Vue or Nuxt](https://metricraven.com/docs/proxy-vue-nuxt)) |
42
+ | `endpoint` | `<script origin>/api/v1/collect` | Where events are sent, e.g. `"/a/event"` behind your own proxy (`data-api`) |
43
+ | `addonsUrl` | next to the script | Where add-ons such as [Page speed](https://metricraven.com/docs/page-speed) and [session replay](https://metricraven.com/docs/session-replay) load from, e.g. `"/a/addons/"` (`data-addons`) |
44
+ | `autoPageviews` | `true` | `false` stops automatic pageviews; call `useMetricRaven().pageview()` yourself |
45
+ | `hashRouting` | `false` | `true` counts `#/route` paths; `"all"` also plain `#anchors` (`data-track-hash`) |
46
+ | `stripQuery` | `false` | Drops query strings from recorded URLs |
47
+ | `consent` | `false` | Storage consent is already granted for every visitor (a persistent visitor ID instead of a daily one) |
48
+ | `adConsent` | `false` | Advertising consent is already granted (or not needed): on sites that [send conversions](https://metricraven.com/docs/send-conversions), the landing page's ad click is sent |
49
+ | `domain` | none | Shares the consented cookie across this domain and its subdomains |
50
+ | `allowLocalhost` | `false` | Also tracks `localhost` and `*.test` |
51
+ | `allowedHostnames` | none | Extra hosts for [cross-domain links](https://metricraven.com/docs/cross-domain), e.g. `["checkout.example.io"]`. The site's own domains are linked automatically |
52
+ | `debug` | `false` | Logs to the browser console what is sent and why anything is skipped |
53
+ | `autocapture` | `true` (all Settings allow) | `false` turns [automatic events](https://metricraven.com/docs/automatic-events) off; a list such as `["clicks", "downloads"]` keeps only those |
54
+
55
+ Each option is the matching `data-*` attribute of the script tag; see [Optional attributes](https://metricraven.com/docs/install#attributes).
56
+
57
+ ### Per environment
58
+
59
+ The options live in public runtime config (`runtimeConfig.public.metricraven`), so Nuxt overrides each one from an environment variable when the server starts: `NUXT_PUBLIC_METRICRAVEN_SITE_ID`, `NUXT_PUBLIC_METRICRAVEN_SCRIPT_URL`, `NUXT_PUBLIC_METRICRAVEN_ALLOW_LOCALHOST=true`, `NUXT_PUBLIC_METRICRAVEN_ALLOWED_HOSTNAMES=a.example.com,b.example.com`, and so on. For a static site (`nuxt generate`), set them where the site is generated.
60
+
61
+ ## Goals, identify and payments
62
+
63
+ `data-goal` on any element records a goal on click, with no code:
64
+
65
+ ```vue
66
+ <button data-goal="signup">Sign up</button>
67
+ ```
68
+
69
+ From your own code, use the auto-imported `useMetricRaven()`. Calls made before the tracker has loaded are queued and sent in order; on the server they do nothing.
70
+
71
+ ```vue
72
+ <script setup lang="ts">
73
+ const { track, identify } = useMetricRaven();
74
+
75
+ function startCheckout() {
76
+ track("checkout_started", { plan: "pro" });
77
+ }
78
+ </script>
79
+ ```
80
+
81
+ It returns the client of [`@metricraven/web`](https://www.npmjs.com/package/@metricraven/web): `track`, `identify`, `payment`, `pageview`, `setConsent`, `setAdConsent`, `reset`, `getVisitorId` and more. See [Goals & funnels](https://metricraven.com/docs/goals-funnels), [Identify users](https://metricraven.com/docs/identify-users) and [Connect a payment provider](https://metricraven.com/docs/connect-payment-provider).
82
+
83
+ ## How it works
84
+
85
+ The module copies its options into `runtimeConfig.public.metricraven`. A plugin renders `<script defer src="https://metricraven.com/js/script.js" data-site-id="…">` with your options as `data-*` attributes into the head of every server-rendered or prerendered page. In the browser, it finds that tag (or adds it, with `ssr: false`) so the tracker loads once, and the tracker records every route change as a pageview. Under a strict Content Security Policy, allow the script's host; with `consent: true` also the one-line inline flag before it. See [Content Security Policy](https://metricraven.com/docs/content-security-policy).
86
+
87
+ Docs: https://metricraven.com/docs/install-vue-nuxt#nuxt-module
88
+
89
+ ## Development
90
+
91
+ ```bash
92
+ npm install
93
+ npm run dev # playground/ with the module
94
+ npm test # unit tests and a built fixture (@nuxt/test-utils)
95
+ npm run build
96
+ ```
97
+
98
+ ## License
99
+
100
+ MIT
@@ -0,0 +1,15 @@
1
+ import * as _nuxt_schema from '@nuxt/schema';
2
+ import { MetricRavenNuxtOptions } from '../dist/runtime/options.js';
3
+ export { MetricRavenNuxtOptions } from '../dist/runtime/options.js';
4
+
5
+ type ModuleOptions = MetricRavenNuxtOptions;
6
+ declare const _default: _nuxt_schema.NuxtModule<MetricRavenNuxtOptions, MetricRavenNuxtOptions, false>;
7
+
8
+ declare module "@nuxt/schema" {
9
+ interface PublicRuntimeConfig {
10
+ metricraven: MetricRavenNuxtOptions;
11
+ }
12
+ }
13
+
14
+ export { _default as default };
15
+ export type { ModuleOptions };
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "@metricraven/nuxt",
3
+ "configKey": "metricraven",
4
+ "compatibility": {
5
+ "nuxt": ">=3.7.0"
6
+ },
7
+ "version": "0.1.0",
8
+ "builder": {
9
+ "@nuxt/module-builder": "1.0.4",
10
+ "unbuild": "3.6.1"
11
+ }
12
+ }
@@ -0,0 +1,28 @@
1
+ import { defineNuxtModule, createResolver, addPlugin, addImports, useLogger } from '@nuxt/kit';
2
+ import { defu } from 'defu';
3
+ import { DEFAULTS, SITE_ID_ENV } from '../dist/runtime/options.js';
4
+
5
+ const DOCS = "https://metricraven.com/docs/install-vue-nuxt#nuxt-module";
6
+ const module$1 = defineNuxtModule({
7
+ meta: {
8
+ name: "@metricraven/nuxt",
9
+ configKey: "metricraven",
10
+ compatibility: { nuxt: ">=3.7.0" }
11
+ },
12
+ defaults: DEFAULTS,
13
+ setup(options, nuxt) {
14
+ const resolver = createResolver(import.meta.url);
15
+ const publicConfig = nuxt.options.runtimeConfig.public;
16
+ publicConfig.metricraven = defu(publicConfig.metricraven, options);
17
+ addPlugin(resolver.resolve("./runtime/plugin"));
18
+ addImports({ name: "useMetricRaven", from: resolver.resolve("./runtime/composables") });
19
+ const configured = publicConfig.metricraven.siteId?.trim() || process.env[SITE_ID_ENV]?.trim();
20
+ if (!configured && !nuxt.options._prepare) {
21
+ useLogger("@metricraven/nuxt").warn(
22
+ `No site ID: set metricraven: { siteId: "ana_pub_\u2026" } in nuxt.config or ${SITE_ID_ENV} where the app runs. Until then the tracker is not added. See ${DOCS}`
23
+ );
24
+ }
25
+ }
26
+ });
27
+
28
+ export { module$1 as default };
@@ -0,0 +1,10 @@
1
+ import { type MetricRavenClient } from "@metricraven/web";
2
+ /**
3
+ * The MetricRaven client: track goals, identify signed-in users, claim payments, set consent.
4
+ * Auto-imported. Calls made before the tracker has loaded are queued and sent in order; on the
5
+ * server they do nothing.
6
+ *
7
+ * const { track } = useMetricRaven();
8
+ * track("checkout_started", { plan: "pro" });
9
+ */
10
+ export declare function useMetricRaven(): MetricRavenClient;
@@ -0,0 +1,4 @@
1
+ import { client } from "@metricraven/web";
2
+ export function useMetricRaven() {
3
+ return client;
4
+ }
@@ -0,0 +1,73 @@
1
+ import { type AutocaptureKind, type MetricRavenOptions } from "@metricraven/web";
2
+ /**
3
+ * The module options (`metricraven: { … }` in nuxt.config). Each one is the matching data-* attribute
4
+ * of the script tag, and each one can be overridden at runtime with NUXT_PUBLIC_METRICRAVEN_<OPTION>.
5
+ */
6
+ export type MetricRavenNuxtOptions = {
7
+ /** Your site ID (ana_pub_…), from Settings. Without one, nothing is added. */
8
+ siteId?: string;
9
+ /** Where MetricRaven is served. Default https://metricraven.com. */
10
+ apiHost?: string;
11
+ /** Full tracker URL, e.g. a same-origin proxy path such as "/a/script". Overrides apiHost. */
12
+ scriptUrl?: string;
13
+ /** Send events here instead of `<script origin>/api/v1/collect` (data-api). */
14
+ endpoint?: string;
15
+ /** Where add-ons load from, e.g. "/a/addons/" (data-addons). */
16
+ addonsUrl?: string;
17
+ /** Record pageviews on load and on every route change. Default true. */
18
+ autoPageviews?: boolean;
19
+ /** Count #/route paths (true), or also plain #anchors ("all"). Default false (data-track-hash). */
20
+ hashRouting?: boolean | "all";
21
+ /** Drop query strings from recorded URLs. Default false. */
22
+ stripQuery?: boolean;
23
+ /** Storage consent is already granted for every visitor. Default false. */
24
+ consent?: boolean;
25
+ /** Advertising consent is already granted, or not needed. Default false (data-ad-consent). */
26
+ adConsent?: boolean;
27
+ /** Share the consented visitor cookie across this domain and its subdomains. */
28
+ domain?: string;
29
+ /** Also track localhost and *.test. Default false. */
30
+ allowLocalhost?: boolean;
31
+ /** Extra hosts for cross-domain links, e.g. ["checkout.example.io"]. */
32
+ allowedHostnames?: string[];
33
+ /** Log to the browser console what is sent and why anything is skipped. Default false. */
34
+ debug?: boolean;
35
+ /**
36
+ * Automatic events: true (default) keeps what Settings allow, false turns them off, a list such as
37
+ * ["clicks", "downloads"] keeps only those.
38
+ */
39
+ autocapture?: boolean | AutocaptureKind[];
40
+ };
41
+ /** Read at runtime when `siteId` is not set in nuxt.config (Nuxt maps it to runtimeConfig.public.metricraven.siteId). */
42
+ export declare const SITE_ID_ENV = "NUXT_PUBLIC_METRICRAVEN_SITE_ID";
43
+ /** Set on the tag this module renders. */
44
+ export declare const SCRIPT_MARKER = "data-metricraven-nuxt";
45
+ /**
46
+ * Every key has a value, so Nuxt can override each one from a NUXT_PUBLIC_METRICRAVEN_* variable
47
+ * (it only overrides keys that exist). Empty strings mean "not set".
48
+ */
49
+ export declare const DEFAULTS: Required<MetricRavenNuxtOptions>;
50
+ /**
51
+ * Runtime config (module options merged with NUXT_PUBLIC_METRICRAVEN_* overrides) as @metricraven/web
52
+ * options, or null without a site ID. Environment values arrive as strings or parsed JSON, so
53
+ * "true", "a.com,b.com" and ["a.com"] are all accepted.
54
+ */
55
+ export declare function resolveOptions(config: MetricRavenNuxtOptions | undefined | null): MetricRavenOptions | null;
56
+ type InlineScript = {
57
+ key: string;
58
+ innerHTML: string;
59
+ };
60
+ type TrackerScript = {
61
+ key: string;
62
+ src: string;
63
+ defer: true;
64
+ } & {
65
+ [attr: `data-${string}`]: string;
66
+ };
67
+ export type HeadScript = InlineScript | TrackerScript;
68
+ /**
69
+ * The head scripts for these options: the tracker tag (same src and data-* attributes as the manual
70
+ * install), preceded by a one-line consent flag when `consent` is on. Empty without a site ID.
71
+ */
72
+ export declare function headScripts(config: MetricRavenNuxtOptions | undefined | null): HeadScript[];
73
+ export {};
@@ -0,0 +1,71 @@
1
+ import { scriptAttributes, scriptSource } from "@metricraven/web";
2
+ export const SITE_ID_ENV = "NUXT_PUBLIC_METRICRAVEN_SITE_ID";
3
+ export const SCRIPT_MARKER = "data-metricraven-nuxt";
4
+ export const DEFAULTS = {
5
+ siteId: "",
6
+ apiHost: "",
7
+ scriptUrl: "",
8
+ endpoint: "",
9
+ addonsUrl: "",
10
+ autoPageviews: true,
11
+ hashRouting: false,
12
+ stripQuery: false,
13
+ consent: false,
14
+ adConsent: false,
15
+ domain: "",
16
+ allowLocalhost: false,
17
+ allowedHostnames: [],
18
+ debug: false,
19
+ autocapture: true
20
+ };
21
+ function text(value) {
22
+ if (value === void 0 || value === null) return void 0;
23
+ const s = String(value).trim();
24
+ return s || void 0;
25
+ }
26
+ function flag(value) {
27
+ return value === true || value === "true" || value === "1";
28
+ }
29
+ function list(value) {
30
+ const items = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
31
+ return items.map((v) => String(v).trim()).filter(Boolean);
32
+ }
33
+ export function resolveOptions(config) {
34
+ const c = config ?? {};
35
+ const siteId = text(c.siteId);
36
+ if (!siteId) return null;
37
+ const hash = c.hashRouting === "all" ? "all" : flag(c.hashRouting);
38
+ const autocapture = c.autocapture === false || c.autocapture === "false" ? false : c.autocapture === true || c.autocapture === void 0 || c.autocapture === "true" || c.autocapture === "" ? void 0 : list(c.autocapture);
39
+ return {
40
+ siteId,
41
+ apiHost: text(c.apiHost),
42
+ scriptUrl: text(c.scriptUrl),
43
+ endpoint: text(c.endpoint),
44
+ addonsUrl: text(c.addonsUrl),
45
+ autoPageviews: !(c.autoPageviews === false || c.autoPageviews === "false"),
46
+ hashRouting: hash,
47
+ stripQuery: flag(c.stripQuery),
48
+ consent: flag(c.consent),
49
+ adConsent: flag(c.adConsent),
50
+ domain: text(c.domain),
51
+ allowLocalhost: flag(c.allowLocalhost),
52
+ allowedHostnames: list(c.allowedHostnames),
53
+ debug: flag(c.debug),
54
+ autocapture
55
+ };
56
+ }
57
+ export function headScripts(config) {
58
+ const options = resolveOptions(config);
59
+ if (!options) return [];
60
+ const scripts = [];
61
+ if (options.consent) scripts.push({ key: "metricraven-consent", innerHTML: "window.metricravenConsent=true" });
62
+ const tracker = {
63
+ key: "metricraven",
64
+ src: scriptSource(options),
65
+ defer: true,
66
+ [SCRIPT_MARKER]: "",
67
+ ...scriptAttributes(options)
68
+ };
69
+ scripts.push(tracker);
70
+ return scripts;
71
+ }
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Server: renders the tracker tag into the page head, so it is in the HTML of every SSR or prerendered
3
+ * page. Browser: init() finds that tag and only connects the queue `useMetricRaven()` writes to; with
4
+ * `ssr: false` (no server HTML) it adds the same tag itself. Either way the tracker loads once and
5
+ * records each route change as a pageview.
6
+ */
7
+ declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
8
+ export default _default;
@@ -0,0 +1,18 @@
1
+ import { init } from "@metricraven/web";
2
+ import { defineNuxtPlugin, useHead, useRuntimeConfig } from "#imports";
3
+ import { headScripts, resolveOptions } from "./options.js";
4
+ export default defineNuxtPlugin({
5
+ name: "metricraven",
6
+ enforce: "pre",
7
+ setup() {
8
+ const config = useRuntimeConfig().public.metricraven;
9
+ if (import.meta.server) {
10
+ const script = headScripts(config);
11
+ if (script.length) useHead({ script });
12
+ return;
13
+ }
14
+ const options = resolveOptions(config);
15
+ if (!options) return;
16
+ init(options);
17
+ }
18
+ });
@@ -0,0 +1,5 @@
1
+ export { type MetricRavenNuxtOptions } from '../dist/runtime/options.js'
2
+
3
+ export { default } from './module.mjs'
4
+
5
+ export { type ModuleOptions } from './module.mjs'
package/package.json CHANGED
@@ -1,6 +1,63 @@
1
1
  {
2
2
  "name": "@metricraven/nuxt",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Nuxt module for MetricRaven: privacy-friendly, revenue-aware web analytics on every page, configured per environment. See which traffic actually pays.",
5
+ "license": "MIT",
6
+ "homepage": "https://metricraven.com/docs/install-vue-nuxt#nuxt-module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/Dual-Ninja-LLC/metricraven-nuxt.git"
10
+ },
11
+ "bugs": "https://github.com/Dual-Ninja-LLC/metricraven-nuxt/issues",
12
+ "keywords": [
13
+ "nuxt",
14
+ "nuxt-module",
15
+ "analytics",
16
+ "metricraven",
17
+ "web-analytics",
18
+ "privacy",
19
+ "revenue-attribution",
20
+ "vue"
21
+ ],
22
+ "type": "module",
23
+ "sideEffects": false,
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/types.d.mts",
27
+ "import": "./dist/module.mjs"
28
+ },
29
+ "./package.json": "./package.json"
30
+ },
31
+ "main": "./dist/module.mjs",
32
+ "files": [
33
+ "dist",
34
+ "README.md",
35
+ "LICENSE"
36
+ ],
37
+ "publishConfig": {
38
+ "access": "public"
39
+ },
40
+ "scripts": {
41
+ "build": "nuxt-module-build prepare && nuxt-module-build build",
42
+ "prepack": "npm run build",
43
+ "dev": "npm run dev:prepare && nuxt dev playground",
44
+ "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
45
+ "test": "nuxt-module-build prepare && vitest run",
46
+ "typecheck": "nuxt-module-build prepare && vue-tsc --noEmit"
47
+ },
48
+ "dependencies": {
49
+ "@metricraven/web": "^0.6.0",
50
+ "@nuxt/kit": "^4.6.4",
51
+ "defu": "^6.1.7"
52
+ },
53
+ "devDependencies": {
54
+ "@nuxt/module-builder": "^1.0.4",
55
+ "@nuxt/schema": "^4.6.4",
56
+ "@nuxt/test-utils": "^4.4.0",
57
+ "@types/node": "^26.6.6",
58
+ "nuxt": "^4.6.4",
59
+ "typescript": "^6.0.3",
60
+ "vitest": "^5.0.5",
61
+ "vue-tsc": "^3.3.12"
62
+ }
63
+ }