@varykit/nuxt 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @varykit/nuxt
+
+**Nuxt 4 module for VaryKit: file-based page testing plus SSR-safe element-level targeting.**
+
+This module depends on `@varykit/vue` and `@varykit/core` as real dependencies — you never need to install them separately.
+
+## The segment model
+
+Every visitor is assigned to a **single global segment** (e.g. `control` or `treatment`), persisted in the `vary:segment` cookie. That segment is reused consistently across every page and element — a visitor is never in different segments for different tests.
+
+## Install
+
+```bash
+pnpm add @varykit/nuxt
+```
+
+## Setup
+
+Add `@varykit/nuxt` to the `modules` array of your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@varykit/nuxt'],
+
+  varyOptions: {
+    duration: 60 * 60 * 24 * 30, // global default: 30 days
+
+    // Global segments — every visitor is assigned to exactly one. The segment
+    // name is the variant file suffix: "a" serves `__a.vue`, "b" serves
+    // `__b.vue`, etc. Files with no matching segment are never served.
+    segments: {
+      a: { distribution: 0.2 },
+      b: { distribution: 0.5 }
+    }
+  }
+})
+```
+
+## File-based page testing
+
+Create variant files using the `__variant` naming convention (flat or folder-based):
+
+```
+pages/
+  contact.__a.vue
+  contact.__b.vue
+  contact.__c.vue
+```
+
+All variants collapse into one route (`/contact`). The visitor's global segment name is used directly as the variant suffix, so with the config above (`segments: { a, b }`) only `contact.__a.vue` and `contact.__b.vue` are served — `contact.__c.vue` is never shown because there is no `c` segment.
+
+## Element-level targeting
+
+`@varykit/nuxt` provides `useSegment` and `<VaryShow>` (auto-imported) with the cookie mechanism swapped to Nuxt's SSR-safe `useCookie` so element targeting is also SSR-consistent (no flash of the wrong variant).
+
+Because segments are already defined in `varyOptions.segments`, `<VaryShow>` picks them up from runtime config automatically — you only pass the `segment` to match:
+
+```vue
+<template>
+  <VaryShow segment="a">
+    <p>A content</p>
+  </VaryShow>
+
+  <VaryShow segment="b">
+    <p>B content</p>
+  </VaryShow>
+</template>
+```
+
+You can still override segments per-use by passing the `:segments` prop explicitly.
+
+## Configuration
+
+### `duration`
+
+Global default cookie duration in seconds. Defaults to 30 days.
+
+### `segments`
+
+The global segment definitions. Each segment supports:
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `distribution` | `number` | Weight between `0` and `1`. Omitted segments auto-split the remainder. |
+| `duration` | `number` | Cookie duration in seconds, overrides the global default for this segment. |
+
+The segment name is the variant file suffix used everywhere — pages and elements simply follow the visitor's segment.
+
+## License
+
+MIT

package/dist/module.d.mts

@@ -0,0 +1,11 @@
+import { NuxtModule } from '@nuxt/schema';
+import { VarySegments } from '@varykit/core';
+
+interface ModuleOptions {
+    duration?: number;
+    segments?: VarySegments;
+}
+declare const module$1: NuxtModule<ModuleOptions>;
+
+export { module$1 as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@varykit/nuxt",
+  "configKey": "varyOptions",
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,75 @@
+import { defineNuxtModule, createResolver, addImports, addComponent } from '@nuxt/kit';
+import { validateSegments } from '@varykit/core';
+
+const FLAT_REGEX = /\.__([a-zA-Z0-9_-]+)$/;
+const FOLDER_REGEX = /\/__([a-zA-Z0-9_-]+)$/;
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@varykit/nuxt",
+    configKey: "varyOptions"
+  },
+  defaults: {
+    duration: 60 * 60 * 24 * 30,
+    // 30 days
+    segments: {}
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    validateSegments(options.segments ?? {});
+    addImports({
+      name: "useSegment",
+      as: "useSegment",
+      from: resolve("./runtime/useSegment")
+    });
+    addComponent({
+      name: "VaryShow",
+      filePath: resolve("./runtime/VaryShow.vue")
+    });
+    nuxt.hook("pages:extend", (pages) => {
+      const groups = {};
+      for (const page of pages) {
+        const name = page.name || "";
+        const flatMatch = name.match(FLAT_REGEX);
+        const folderMatch = name.match(FOLDER_REGEX);
+        const match = flatMatch || folderMatch;
+        if (!match) continue;
+        const base = name.slice(0, match.index);
+        const variant = match[1];
+        groups[base] ??= [];
+        groups[base].push({ page, variant });
+      }
+      for (const [base, entries] of Object.entries(groups)) {
+        if (entries.length < 2) continue;
+        for (const { page } of entries) {
+          const idx = pages.indexOf(page);
+          if (idx !== -1) pages.splice(idx, 1);
+        }
+        const rawPath = entries[0].page.path;
+        const cleanPath = rawPath.replace(/\.__[a-zA-Z0-9_-]+$/, "").replace(/\/__[a-zA-Z0-9_-]+$/, "") || "/";
+        const configKey = cleanPath.replace(/^\//, "");
+        const plainIndex = pages.findIndex(
+          (p) => (p.name === base || p.path === cleanPath) && !p.file.includes("vary-resolver")
+        );
+        const hasFallback = plainIndex !== -1;
+        if (plainIndex !== -1) pages.splice(plainIndex, 1);
+        const variantNames = entries.map((e) => e.variant);
+        pages.push({
+          name: base || "index",
+          path: cleanPath,
+          file: resolve("./runtime/vary-resolver.vue"),
+          meta: {
+            varyBase: configKey,
+            varyVariants: variantNames,
+            varyFallback: hasFallback
+          }
+        });
+      }
+    });
+    nuxt.options.runtimeConfig.public.varyOptions = {
+      duration: options.duration,
+      segments: options.segments
+    };
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/VaryShow.d.vue.ts

@@ -0,0 +1,18 @@
+import type { VarySegments } from '@varykit/core';
+type __VLS_Props = {
+    segment: string;
+    segments?: VarySegments;
+    duration?: number;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/VaryShow.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { useSegment } from "./useSegment";
+const props = defineProps({
+  segment: { type: String, required: true },
+  segments: { type: Object, required: false },
+  duration: { type: Number, required: false }
+});
+const runtimeConfig = useRuntimeConfig().public.varyOptions;
+const segments = props.segments ?? runtimeConfig.segments ?? {};
+const { segment } = useSegment(segments, {
+  duration: props.duration
+});
+</script>
+
+<template>
+  <slot v-if="segment === props.segment" />
+</template>

package/dist/runtime/VaryShow.vue.d.ts

@@ -0,0 +1,18 @@
+import type { VarySegments } from '@varykit/core';
+type __VLS_Props = {
+    segment: string;
+    segments?: VarySegments;
+    duration?: number;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/useSegment.d.ts

@@ -0,0 +1,17 @@
+import { type Ref } from 'vue';
+import { type VarySegments } from '@varykit/core';
+export interface UseSegmentOptions {
+    duration?: number;
+    cookieName?: string;
+}
+export interface UseSegmentReturn {
+    segment: Ref<string>;
+}
+/**
+ * Nuxt-specific global segment resolution.
+ *
+ * Identical API to `@varykit/vue`'s `useSegment`, but persists the assignment
+ * via Nuxt's SSR-safe `useCookie` so the resolved segment is consistent
+ * between server and client (no flash of the wrong variant).
+ */
+export declare function useSegment(segments: VarySegments, options?: UseSegmentOptions): UseSegmentReturn;

package/dist/runtime/useSegment.js

@@ -0,0 +1,13 @@
+import { ref } from "vue";
+import { resolveSegment } from "@varykit/core";
+export function useSegment(segments, options = {}) {
+  const cookieName = options.cookieName ?? "vary:segment";
+  const cookie = useCookie(cookieName);
+  const resolved = resolveSegment({
+    segments,
+    existingSegment: cookie.value,
+    defaultDuration: options.duration
+  });
+  useCookie(cookieName, { maxAge: resolved.duration }).value = resolved.segment;
+  return { segment: ref(resolved.segment) };
+}

package/dist/runtime/vary-resolver.d.vue.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/vary-resolver.vue

@@ -0,0 +1,35 @@
+<script setup>
+import { resolveSegment } from "@varykit/core";
+const route = useRoute();
+const runtimeConfig = useRuntimeConfig().public.varyOptions;
+const base = route.meta.varyBase;
+const discoveredVariants = route.meta.varyVariants;
+const hasFallback = route.meta.varyFallback === true;
+const globalDuration = runtimeConfig.duration;
+const segments = runtimeConfig.segments || {};
+const cookieName = "vary:segment";
+const cookie = useCookie(cookieName);
+const resolved = resolveSegment({
+  segments,
+  existingSegment: cookie.value,
+  defaultDuration: globalDuration
+});
+useCookie(cookieName, { maxAge: resolved.duration }).value = resolved.segment;
+const variant = resolved.segment;
+const modules = import.meta.glob("~/pages/**/*.vue");
+const variantKey = Object.keys(modules).find(
+  (k) => k.endsWith(`.__${variant}.vue`) || k.endsWith(`/__${variant}.vue`)
+);
+const fallbackKey = hasFallback ? Object.keys(modules).find(
+  (k) => k.endsWith(`/${base}.vue`) && !/\.__[a-zA-Z0-9_-]+\.vue$/.test(k)
+) : void 0;
+const key = variantKey ?? fallbackKey ?? discoveredVariants[0];
+if (!key) {
+  throw new Error(`[varykit] No variant file for segment "${variant}" of "${base}".`);
+}
+const VariantComponent = defineAsyncComponent(() => modules[key]());
+</script>
+
+<template>
+  <VariantComponent />
+</template>

package/dist/runtime/vary-resolver.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@varykit/nuxt",
+  "version": "0.1.0",
+  "description": "Nuxt 4 module for VaryKit: file-based page testing plus SSR-safe element-level targeting.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt-module-build",
+    "dev:prepare": "nuxt-module-build --stub",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "a/b-testing",
+    "multivariate",
+    "ab-test",
+    "experimentation",
+    "bucketing",
+    "varykit"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^4.0.0",
+    "@varykit/core": "workspace:*",
+    "@varykit/vue": "workspace:*"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "1.0.2",
+    "@nuxt/schema": "^4.0.0",
+    "nuxt": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vue": "^3.0.0",
+    "vue-tsc": "^2.0.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0"
+  }
+}