@varykit/nuxt

@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

pnpm add @varykit/nuxt

Setup

Add @varykit/nuxt to the modules array of your nuxt.config.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:

<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