How to add feature flags and experiments to a Nuxt app

{
  "defaultTemplate": "kanban",
  "showTemplateGallery": true
}

npm install @amplitude/experiment-node-server

export default defineNuxtConfig({
  runtimeConfig: {
    // Server only. Filled from NUXT_AMPLITUDE_SERVER_DEPLOYMENT_KEY.
    amplitudeServerDeploymentKey: '',
    public: {
      // Filled from NUXT_PUBLIC_AMPLITUDE_API_KEY.
      amplitudeApiKey: '',
    },
  },
});

NUXT_PUBLIC_AMPLITUDE_API_KEY=your-project-api-key
NUXT_AMPLITUDE_SERVER_DEPLOYMENT_KEY=your-server-deployment-key

import { Experiment } from '@amplitude/experiment-node-server';

type LocalClient = ReturnType<typeof Experiment.initializeLocal>;
export type ServerVariants = ReturnType<LocalClient['evaluateV2']>;
export type ExperimentUser = { user_id?: string; device_id?: string };

let client: LocalClient | undefined;
let ready: Promise<void> | undefined;

function getClient() {
  if (!client) {
    const key = useRuntimeConfig().amplitudeServerDeploymentKey;
    if (!key) throw new Error('NUXT_AMPLITUDE_SERVER_DEPLOYMENT_KEY is not set');

    const localClient = Experiment.initializeLocal(key);
    client = localClient;
    // start() downloads the flag rules and polls for updates.
    ready = localClient.start().catch((error) => {
      // Don't leave a poller running for a client we drop, and let the
      // next request try again instead of failing forever.
      localClient.stop();
      client = undefined;
      throw error;
    });
  }
  return { client: client!, ready: ready! };
}

// Evaluates the given flags for one user in memory. Returns {} on any
// failure, so pages render their defaults instead of erroring.
export async function evaluateFlags(
  user: ExperimentUser,
  flagKeys: string[],
): Promise<ServerVariants> {
  if (!user.user_id && !user.device_id) return {};

  try {
    const { client, ready } = getClient();
    // Wait at most 1 second for the first download, so a cold start or an
    // outage renders defaults instead of holding the page.
    let timer: ReturnType<typeof setTimeout> | undefined;
    const timeout = new Promise<never>((_, reject) => {
      timer = setTimeout(() => reject(new Error('flag rules not loaded in time')), 1000);
    });
    try {
      await Promise.race([ready, timeout]);
    } finally {
      clearTimeout(timer);
    }
    return client.evaluateV2(user, flagKeys);
  } catch (error) {
    console.error('[flags] evaluation failed; rendering defaults.', error);
    return {};
  }
}

const client = Experiment.initializeRemote(key, {
  fetchTimeoutMillis: 500,
  fetchRetries: 1,
  fetchRetryBackoffMinMillis: 0,
  fetchRetryTimeoutMillis: 500,
});

// per request, instead of evaluateV2 (no start() needed):
const variants = await client.fetchV2(user, { flagKeys });

import { randomUUID } from 'node:crypto';
import { AmplitudeCookie } from '@amplitude/experiment-node-server';

// Only flags your pages render. Every key here ends up in the page
// payload, where anyone can read it in the page source.
const CLIENT_FLAG_KEYS = ['new-project-flow'];

export default defineEventHandler(async (event) => {
  const apiKey = useRuntimeConfig(event).public.amplitudeApiKey;

  let deviceId: string | undefined;
  if (apiKey) {
    // `true` selects the Browser SDK 2 cookie format, which unified uses.
    const cookie = getCookie(event, AmplitudeCookie.cookieName(apiKey, true));
    if (cookie) {
      try {
        deviceId = AmplitudeCookie.parse(cookie, true).device_id ?? undefined;
      } catch {
        deviceId = undefined;
      }
    }
  }

  // First visit: no cookie yet. The browser SDK adopts this ID (step 4).
  const newDeviceId = !deviceId;
  deviceId ??= randomUUID();

  // Your auth: replace with however your server reads the signed-in user.
  const rawUserId = (event.context.user as { id?: string } | undefined)?.id;
  // The same "user-" prefix the browser sets, so both sides send one ID.
  const userId = rawUserId ? `user-${rawUserId}` : undefined;

  const variants = await evaluateFlags(
    { device_id: deviceId, user_id: userId },
    CLIENT_FLAG_KEYS,
  );

  // Plain objects only, and nothing for users outside the rollout.
  const flags: Record<string, { value: string; payload?: unknown }> = {};
  for (const [flagKey, variant] of Object.entries(variants)) {
    if (variant?.value && variant.value !== 'off') {
      flags[flagKey] = { value: variant.value, payload: variant.payload };
    }
  }

  // One visitor's variants; never cache them for anyone else.
  setResponseHeader(event, 'cache-control', 'private, no-store');
  return { deviceId, newDeviceId, userId, flags };
});

import { setResponseHeader } from 'h3';
import type { AmplitudeFlags } from '~/composables/useVariant';

// Paths you serve from a cache (swr, isr, or cache route rules, or a CDN).
// Their HTML is shared, so it must never carry one visitor's device ID.
const CACHED_PATH_PREFIXES: string[] = [];

export default defineNuxtPlugin(async () => {
  const state = useState<AmplitudeFlags | null>('amplitude-flags', () => null);

  // Prerendered HTML is shared by every visitor. Don't freeze one
  // visitor's device ID and variants into it.
  if (import.meta.prerender) return;
  const path = useRequestURL().pathname;
  if (CACHED_PATH_PREFIXES.some((prefix) => path.startsWith(prefix))) return;

  // From here on, this page's HTML carries one visitor's device ID and
  // variants, so no cache may store it.
  const event = useRequestEvent();
  if (event) setResponseHeader(event, 'cache-control', 'private, no-store');

  try {
    // useRequestFetch forwards this request's cookies, so the route sees
    // the AMP_ cookie and your session.
    state.value = await useRequestFetch()('/api/flags');
  } catch (error) {
    console.error('[flags] could not load flags; rendering defaults.', error);
  }
});

import * as amplitude from '@amplitude/unified';
import type { AmplitudeFlags } from '~/composables/useVariant';

export default defineNuxtPlugin(() => {
  const apiKey = useRuntimeConfig().public.amplitudeApiKey;

  if (!apiKey) {
    console.warn('NUXT_PUBLIC_AMPLITUDE_API_KEY is not set; analytics is off.');
    return { provide: { amplitudeReady: Promise.resolve(false) } };
  }

  // What the server evaluated with, from the page payload.
  const server = useState<AmplitudeFlags | null>('amplitude-flags').value;

  // Adopt the server's device ID only if this browser has no Amplitude
  // cookie yet, so a stale or shared payload can't replace an existing ID.
  // Browser SDK 2 names it AMP_ plus the first 10 characters of the key.
  const hasAmpCookie = document.cookie
    .split('; ')
    .some((c) => c.startsWith(`AMP_${apiKey.slice(0, 10)}=`));
  const adoptServerDeviceId = Boolean(server?.newDeviceId) && !hasAmpCookie;

  // initAll is typed void; wrapping it keeps the .then() safe either way.
  const ready = Promise.resolve(
    amplitude.initAll(apiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
        // First visit only: adopt the device ID the server bucketed.
        // Later visits read it from the AMP_ cookie.
        ...(adoptServerDeviceId ? { deviceId: server!.deviceId } : {}),
        // The user the server evaluated, set before the first event.
        ...(server?.userId ? { userId: server.userId } : {}),
      },
      sessionReplay: {
        // Every session while you build; about 1% in production.
        sampleRate: import.meta.dev ? 1 : 0.01,
      },
    }),
  ).then(() => true);

  return { provide: { amplitudeReady: ready } };
});

import { computed, onMounted } from 'vue';
import * as amplitude from '@amplitude/unified';

export type ServerVariant = { value: string; payload?: unknown };
export type AmplitudeFlags = {
  deviceId: string;
  newDeviceId: boolean;
  userId?: string;
  flags: Record<string, ServerVariant>;
};

export function useVariant(flagKey: string, { trackOnMount = true } = {}) {
  const state = useState<AmplitudeFlags | null>('amplitude-flags', () => null);
  const nuxtApp = useNuxtApp();
  const variant = computed(() => state.value?.flags[flagKey]);

  function trackExposure() {
    const value = variant.value?.value;
    // No variant means the user isn't in the rollout. An exposure without
    // a variant would remove them from the experiment, so send nothing.
    if (!value) return;

    void nuxtApp.$amplitudeReady.then((ok) => {
      if (ok) amplitude.track('$exposure', { flag_key: flagKey, variant: value });
    });
  }

  // onMounted never runs on the server, and runs after the browser has
  // shown the variant.
  if (trackOnMount) onMounted(trackExposure);

  return { variant, trackExposure };
}

<script setup lang="ts">
import { ref } from 'vue';
import * as amplitude from '@amplitude/unified';

const TEMPLATES = ['blank', 'kanban', 'roadmap'];

type NewProjectPayload = {
  defaultTemplate?: unknown;
  showTemplateGallery?: unknown;
};

const { variant } = useVariant('new-project-flow');

// Only the "on" variant carries the new settings. Validate the payload
// and keep the current defaults for anything missing or unexpected.
const config = (variant.value?.value === 'on' ? variant.value.payload : undefined) as
  | NewProjectPayload
  | undefined;
const defaultTemplate =
  typeof config?.defaultTemplate === 'string' && TEMPLATES.includes(config.defaultTemplate)
    ? config.defaultTemplate
    : 'blank';
const showGallery = config?.showTemplateGallery === true;

const template = ref(defaultTemplate);

async function handleCreate() {
  // ... your create logic

  amplitude.track('Project Created', { template: template.value });
}
</script>

<template>
  <div>
    <fieldset v-if="showGallery">
      <legend>Start from a template</legend>
      <label v-for="t in TEMPLATES" :key="t">
        <input v-model="template" type="radio" name="template" :value="t" />
        {{ t }}
      </label>
    </fieldset>
    <select v-else v-model="template">
      <option v-for="t in TEMPLATES" :key="t" :value="t">{{ t }}</option>
    </select>
    <button @click="handleCreate">Create project</button>
  </div>
</template>

import * as amplitude from '@amplitude/unified';

export async function signOut() {
  // ... your sign-out logic

  // Clears the user ID and issues a new device ID for the next person.
  amplitude.reset();
  // A full load, so the server evaluates the signed-out visitor.
  reloadNuxtApp({ path: '/' });
}

export function afterSignIn(redirectTo = '/') {
  // The current payload was evaluated for an anonymous visitor. A full
  // load evaluates again with the signed-in user's ID.
  reloadNuxtApp({ path: redirectTo });
}

// -- nuxt.config.ts --
export default defineNuxtConfig({
  runtimeConfig: {
    amplitudeServerDeploymentKey: '',
    public: {
      amplitudeApiKey: '',
    },
  },
});

// -- .env --
NUXT_PUBLIC_AMPLITUDE_API_KEY=your-project-api-key
NUXT_AMPLITUDE_SERVER_DEPLOYMENT_KEY=your-server-deployment-key

// -- server/utils/experiment.ts --
import { Experiment } from '@amplitude/experiment-node-server';

type LocalClient = ReturnType<typeof Experiment.initializeLocal>;
export type ServerVariants = ReturnType<LocalClient['evaluateV2']>;
export type ExperimentUser = { user_id?: string; device_id?: string };

let client: LocalClient | undefined;
let ready: Promise<void> | undefined;

function getClient() {
  if (!client) {
    const key = useRuntimeConfig().amplitudeServerDeploymentKey;
    if (!key) throw new Error('NUXT_AMPLITUDE_SERVER_DEPLOYMENT_KEY is not set');

    const localClient = Experiment.initializeLocal(key);
    client = localClient;
    ready = localClient.start().catch((error) => {
      localClient.stop();
      client = undefined;
      throw error;
    });
  }
  return { client: client!, ready: ready! };
}

export async function evaluateFlags(
  user: ExperimentUser,
  flagKeys: string[],
): Promise<ServerVariants> {
  if (!user.user_id && !user.device_id) return {};

  try {
    const { client, ready } = getClient();
    let timer: ReturnType<typeof setTimeout> | undefined;
    const timeout = new Promise<never>((_, reject) => {
      timer = setTimeout(() => reject(new Error('flag rules not loaded in time')), 1000);
    });
    try {
      await Promise.race([ready, timeout]);
    } finally {
      clearTimeout(timer);
    }
    return client.evaluateV2(user, flagKeys);
  } catch (error) {
    console.error('[flags] evaluation failed; rendering defaults.', error);
    return {};
  }
}

// -- server/api/flags.get.ts --
import { randomUUID } from 'node:crypto';
import { AmplitudeCookie } from '@amplitude/experiment-node-server';

const CLIENT_FLAG_KEYS = ['new-project-flow'];

export default defineEventHandler(async (event) => {
  const apiKey = useRuntimeConfig(event).public.amplitudeApiKey;

  let deviceId: string | undefined;
  if (apiKey) {
    const cookie = getCookie(event, AmplitudeCookie.cookieName(apiKey, true));
    if (cookie) {
      try {
        deviceId = AmplitudeCookie.parse(cookie, true).device_id ?? undefined;
      } catch {
        deviceId = undefined;
      }
    }
  }

  const newDeviceId = !deviceId;
  deviceId ??= randomUUID();

  const rawUserId = (event.context.user as { id?: string } | undefined)?.id;
  const userId = rawUserId ? `user-${rawUserId}` : undefined;

  const variants = await evaluateFlags(
    { device_id: deviceId, user_id: userId },
    CLIENT_FLAG_KEYS,
  );

  const flags: Record<string, { value: string; payload?: unknown }> = {};
  for (const [flagKey, variant] of Object.entries(variants)) {
    if (variant?.value && variant.value !== 'off') {
      flags[flagKey] = { value: variant.value, payload: variant.payload };
    }
  }

  setResponseHeader(event, 'cache-control', 'private, no-store');
  return { deviceId, newDeviceId, userId, flags };
});

// -- app/plugins/experiment.server.ts --
import { setResponseHeader } from 'h3';
import type { AmplitudeFlags } from '~/composables/useVariant';

const CACHED_PATH_PREFIXES: string[] = [];

export default defineNuxtPlugin(async () => {
  const state = useState<AmplitudeFlags | null>('amplitude-flags', () => null);

  if (import.meta.prerender) return;
  const path = useRequestURL().pathname;
  if (CACHED_PATH_PREFIXES.some((prefix) => path.startsWith(prefix))) return;

  const event = useRequestEvent();
  if (event) setResponseHeader(event, 'cache-control', 'private, no-store');

  try {
    state.value = await useRequestFetch()('/api/flags');
  } catch (error) {
    console.error('[flags] could not load flags; rendering defaults.', error);
  }
});

// -- app/plugins/amplitude.client.ts --
import * as amplitude from '@amplitude/unified';
import type { AmplitudeFlags } from '~/composables/useVariant';

export default defineNuxtPlugin(() => {
  const apiKey = useRuntimeConfig().public.amplitudeApiKey;

  if (!apiKey) {
    console.warn('NUXT_PUBLIC_AMPLITUDE_API_KEY is not set; analytics is off.');
    return { provide: { amplitudeReady: Promise.resolve(false) } };
  }

  const server = useState<AmplitudeFlags | null>('amplitude-flags').value;
  const hasAmpCookie = document.cookie
    .split('; ')
    .some((c) => c.startsWith(`AMP_${apiKey.slice(0, 10)}=`));
  const adoptServerDeviceId = Boolean(server?.newDeviceId) && !hasAmpCookie;

  const ready = Promise.resolve(
    amplitude.initAll(apiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
        ...(adoptServerDeviceId ? { deviceId: server!.deviceId } : {}),
        ...(server?.userId ? { userId: server.userId } : {}),
      },
      sessionReplay: {
        sampleRate: import.meta.dev ? 1 : 0.01,
      },
    }),
  ).then(() => true);

  return { provide: { amplitudeReady: ready } };
});

// -- app/composables/useVariant.ts --
import { computed, onMounted } from 'vue';
import * as amplitude from '@amplitude/unified';

export type ServerVariant = { value: string; payload?: unknown };
export type AmplitudeFlags = {
  deviceId: string;
  newDeviceId: boolean;
  userId?: string;
  flags: Record<string, ServerVariant>;
};

export function useVariant(flagKey: string, { trackOnMount = true } = {}) {
  const state = useState<AmplitudeFlags | null>('amplitude-flags', () => null);
  const nuxtApp = useNuxtApp();
  const variant = computed(() => state.value?.flags[flagKey]);

  function trackExposure() {
    const value = variant.value?.value;
    if (!value) return;

    void nuxtApp.$amplitudeReady.then((ok) => {
      if (ok) amplitude.track('$exposure', { flag_key: flagKey, variant: value });
    });
  }

  if (trackOnMount) onMounted(trackExposure);

  return { variant, trackExposure };
}

// -- app/pages/projects/new.vue --
<script setup lang="ts">
import { ref } from 'vue';
import * as amplitude from '@amplitude/unified';

const TEMPLATES = ['blank', 'kanban', 'roadmap'];

type NewProjectPayload = {
  defaultTemplate?: unknown;
  showTemplateGallery?: unknown;
};

const { variant } = useVariant('new-project-flow');

const config = (variant.value?.value === 'on' ? variant.value.payload : undefined) as
  | NewProjectPayload
  | undefined;
const defaultTemplate =
  typeof config?.defaultTemplate === 'string' && TEMPLATES.includes(config.defaultTemplate)
    ? config.defaultTemplate
    : 'blank';
const showGallery = config?.showTemplateGallery === true;

const template = ref(defaultTemplate);

async function handleCreate() {
  // ... your create logic
  amplitude.track('Project Created', { template: template.value });
}
</script>

<template>
  <div>
    <fieldset v-if="showGallery">
      <legend>Start from a template</legend>
      <label v-for="t in TEMPLATES" :key="t">
        <input v-model="template" type="radio" name="template" :value="t" />
        {{ t }}
      </label>
    </fieldset>
    <select v-else v-model="template">
      <option v-for="t in TEMPLATES" :key="t" :value="t">{{ t }}</option>
    </select>
    <button @click="handleCreate">Create project</button>
  </div>
</template>

// -- app/utils/signOut.ts --
import * as amplitude from '@amplitude/unified';

export async function signOut() {
  // ... your sign-out logic
  amplitude.reset();
  reloadNuxtApp({ path: '/' });
}

// -- app/utils/afterSignIn.ts --
export function afterSignIn(redirectTo = '/') {
  reloadNuxtApp({ path: redirectTo });
}

Add server-evaluated Amplitude feature flags to this Nuxt app by following
https://amplitude.com/build/nuxt-feature-flags exactly. It builds on
https://amplitude.com/build/nuxt-product-analytics; don't reinstall unified
or add a second initAll. Install @amplitude/experiment-node-server. Put the
server deployment key in runtimeConfig.amplitudeServerDeploymentKey (top
level, never under public), filled from NUXT_AMPLITUDE_SERVER_DEPLOYMENT_KEY,
and only read it in server/utils/experiment.ts, which keeps one local
evaluation client per process, calls stop() on a client whose start()
fails, and waits at most 1 second for start() before evaluateV2. In
server/api/flags.get.ts, read the device ID from the AMP_ cookie with
AmplitudeCookie.cookieName(apiKey, true) and parse(value, true), generate a
UUID only when there's no cookie, build the user ID with the same "user-"
prefix as the browser, evaluate only CLIENT_FLAG_KEYS, and return plain
{ value, payload } objects with cache-control private, no-store. Call the
route from app/plugins/experiment.server.ts with useRequestFetch, skip it
when prerendering, and store the result in useState('amplitude-flags'). The
flags plugin runs on every server-rendered page: mark that HTML private,
no-store, and skip paths listed in CACHED_PATH_PREFIXES. In
app/plugins/amplitude.client.ts, pass analytics.deviceId only when
newDeviceId is true and the browser has no AMP_ cookie for the API key, and
pass analytics.userId from the payload. Read variants with useVariant in the
page that renders them, never with experiment().variant(), and track
$exposure from onMounted (or from trackExposure when hidden UI opens) only
when there's a variant. Don't track exposures on the server. End sign-in and
sign-out with reloadNuxtApp, and call reset() only from the sign-out
handler. Don't invent flag keys. Report every file you changed. On Nuxt 3
without an app/ folder, drop the app/ prefix from every path; server/ stays
at the root either way.