How to add feature flags and experiments to a React Router app (formerly Remix)

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

npm install @amplitude/experiment-node-server

VITE_AMPLITUDE_API_KEY=your-project-api-key
VITE_AMPLITUDE_DEPLOYMENT_KEY=your-client-deployment-key
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;
  user_properties?: Record<string, string>;
};

// Vite re-runs server modules when you edit them in development. Keeping the
// client on globalThis means one client per process, not one per edit.
const store = globalThis as typeof globalThis & {
  __amplitudeFlags?: { client: LocalClient; ready: Promise<void> };
};

// Creates the client once per process and starts downloading flag rules.
// The first evaluation calls it; nothing starts when the module loads.
export function startFlags(): Promise<void> {
  if (!store.__amplitudeFlags) {
    const key = process.env.AMPLITUDE_SERVER_DEPLOYMENT_KEY;
    if (!key) return Promise.reject(new Error("AMPLITUDE_SERVER_DEPLOYMENT_KEY is not set"));

    const client = Experiment.initializeLocal(key);
    // react-router-serve closes its server on SIGTERM and SIGINT but doesn't
    // exit, and the flag poller would keep Node running. Stop it there.
    for (const signal of ["SIGTERM", "SIGINT"] as const) {
      if (process.listenerCount(signal) > 0) process.once(signal, () => client.stop());
    }
    // start() downloads the flag rules, then polls for updates.
    const ready = client.start().catch((error) => {
      // Stop polling for the dropped client; the next request retries.
      client.stop();
      if (store.__amplitudeFlags?.client === client) store.__amplitudeFlags = undefined;
      throw error;
    });
    store.__amplitudeFlags = { client, ready };
  }
  return store.__amplitudeFlags.ready;
}

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

  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    const started = startFlags();
    const current = store.__amplitudeFlags?.client;
    // A cold start or outage renders defaults instead of holding the page.
    await Promise.race([
      started,
      new Promise<never>((_, reject) => {
        timer = setTimeout(() => reject(new Error("flag rules not loaded within 1 s")), 1000);
      }),
    ]);
    return current ? current.evaluateV2(user, flagKeys) : {};
  } catch (error) {
    console.error("[flags] evaluation failed; rendering defaults.", error);
    return {};
  } finally {
    clearTimeout(timer);
  }
}

// Set by the server when it evaluates flags for a visitor who has no
// AMP_ cookie yet. Not the SDK's own cookie.
export const DEVICE_ID_HANDOFF_COOKIE = "amp_server_device_id";

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isDeviceId(value: string | undefined): value is string {
  return value !== undefined && UUID.test(value);
}

// Reads one cookie from a Cookie header or document.cookie.
export function readCookie(cookies: string, name: string): string | undefined {
  const prefix = `${name}=`;
  const match = cookies.split(/;\s*/).find((c) => c.startsWith(prefix));
  if (!match) return undefined;
  // A malformed cookie must not stop the page from rendering or hydrating.
  try {
    return decodeURIComponent(match.slice(prefix.length));
  } catch {
    return undefined;
  }
}

import { randomUUID } from "node:crypto";
import { AmplitudeCookie } from "@amplitude/experiment-node-server";
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId, readCookie } from "./amplitude-cookies";
import type { ServerFlags } from "./flags";
import { evaluateFlags } from "./experiment.server";

type FlagUser = { id: string | number; plan?: string | null } | null;

function readDeviceId(cookies: string): string | undefined {
  const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;
  if (!apiKey) return undefined;
  // cookieName throws on a malformed key: render defaults, not an error.
  try {
    // `true` selects the Browser SDK 2 cookie format, which unified uses.
    const cookie = readCookie(cookies, AmplitudeCookie.cookieName(apiKey, true));
    return cookie ? (AmplitudeCookie.parse(cookie, true).device_id ?? undefined) : undefined;
  } catch {
    return undefined;
  }
}

export async function loadFlags(
  request: Request,
  user: FlagUser,
  flagKeys: string[],
): Promise<{ flags: ServerFlags; headers: Headers }> {
  // This response carries one visitor's device ID and variants. No cache may store it.
  const headers = new Headers({ "Cache-Control": "private, no-store" });
  const cookies = request.headers.get("Cookie") ?? "";

  // 1. The browser SDK's own cookie.
  // 2. An ID this server minted earlier that the browser hasn't adopted yet.
  // 3. A new ID, handed to the browser for step 5.
  let deviceId = readDeviceId(cookies);
  if (!deviceId) {
    const handoff = readCookie(cookies, DEVICE_ID_HANDOFF_COOKIE);
    if (isDeviceId(handoff)) deviceId = handoff;
  }
  if (!deviceId) {
    deviceId = randomUUID();
    // Not HttpOnly: the client entry reads it.
    headers.append(
      "Set-Cookie",
      `${DEVICE_ID_HANDOFF_COOKIE}=${deviceId}; Path=/; Max-Age=3600; SameSite=Lax`,
    );
  }

  // The same "user-" prefix the browser sets, so both sides send one ID.
  const userId = user ? `user-${user.id}` : undefined;

  const variants = await evaluateFlags(
    {
      device_id: deviceId,
      user_id: userId,
      // Local evaluation only sees the properties you pass in.
      ...(user ? { user_properties: { plan: user.plan ?? "unknown" } } : {}),
    },
    flagKeys,
  );

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

  return { flags: { deviceId, userId, flags }, headers };
}

// Resolves to true once initAll has finished in the browser, or false
// if analytics is off. Nothing awaits it on the server.
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

export function setAmplitudeReady(init: Promise<unknown> | null) {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error) => {
      console.warn("[amplitude] initAll failed", error);
      markReady(false);
    },
  );
}

// Keep lines other React Router pages added here: pageViews: { trackHistoryChanges: "pathOnly" }
// (/build/react-router-web-analytics), debugMode and privacyConfig (/build/react-router-session-replay),
// the setAmplitudeReady(...) wrapper and setAmplitudeReady(null) (/build/react-router-guides-surveys),
// and the amplitude.add(webExperiment.plugin()) lines (/build/react-router-web-experiment).
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";
import * as amplitude from "@amplitude/unified";
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId, readCookie } from "./lib/amplitude-cookies";
import { setAmplitudeReady } from "./lib/amplitude-ready";

const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;

if (apiKey) {
  // Browser SDK 2 names its cookie AMP_ plus the first 10 characters of
  // the key. If it exists, the SDK already has a device ID: keep it.
  const hasAmpCookie = readCookie(document.cookie, `AMP_${apiKey.slice(0, 10)}`) !== undefined;
  const serverDeviceId = readCookie(document.cookie, DEVICE_ID_HANDOFF_COOKIE);
  const adoptServerDeviceId = !hasAmpCookie && isDeviceId(serverDeviceId);

  // Steps 6 and 7 wait for this promise before they read from the SDK.
  setAmplitudeReady(
    amplitude.initAll(apiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
        // First visit only: the device ID the server bucketed this visitor
        // with. Later visits read it from the AMP_ cookie the SDK writes.
        ...(adoptServerDeviceId ? { deviceId: serverDeviceId } : {}),
      },
      sessionReplay: {
        // Every session while you build; about 1% in production.
        sampleRate: import.meta.env.DEV ? 1 : 0.01,
        debugMode: import.meta.env.DEV,
        privacyConfig: {
          maskSelector: ["[data-amp-mask]"],
          blockSelector: ["[data-amp-block]"],
          unmaskSelector: ["[data-amp-unmask]"],
        },
      },
      experiment: {
        // The client deployment key, for the browser flags in step 7.
        deploymentKey: import.meta.env.VITE_AMPLITUDE_DEPLOYMENT_KEY,
        // Default is 10 seconds. Fall back to the current UI sooner.
        fetchTimeoutMillis: 3000,
      },
    }),
  );
} else {
  console.warn("VITE_AMPLITUDE_API_KEY is not set; analytics is off.");
  setAmplitudeReady(null);
}

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>
  );
});

import { useEffect, useRef } from "react";
import * as amplitude from "@amplitude/unified";
import { amplitudeReady } from "./amplitude-ready";

export type FlagVariant = { value: string; payload?: unknown };
export type ServerFlags = {
  deviceId: string;
  userId?: string;
  flags: Record<string, FlagVariant>;
};

export function useServerFlag(state: ServerFlags | null | undefined, flagKey: string) {
  const variant = state?.flags[flagKey];
  const value = variant?.value;
  const deviceId = state?.deviceId;
  const userId = state?.userId;
  const lastExposure = useRef<string | undefined>(undefined);

  // Browser only, after the variant is on screen.
  useEffect(() => {
    // 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 (!deviceId || !value) return;

    // Once per visit and identity, even when the loader data reloads or
    // StrictMode runs the effect twice.
    const key = `${userId ?? ""}|${deviceId}|${value}`;
    if (key === lastExposure.current) return;
    lastExposure.current = key;

    // getDeviceId() is undefined until initAll settles.
    void amplitudeReady.then((ok) => {
      if (!ok) return;
      const browserDeviceId = amplitude.getDeviceId();
      const browserUserId = amplitude.getUserId();
      // A variant evaluated for another device or user isn't this
      // visitor's: send nothing.
      const sameDevice = browserDeviceId === deviceId;
      const sameUser = !userId || !browserUserId || browserUserId === userId;
      if (!sameDevice || !sameUser) {
        if (import.meta.env.DEV) {
          console.warn(
            `[flags] no exposure for ${flagKey}: the browser's device or user differs from what the server evaluated.`,
          );
        }
        return;
      }

      amplitude.track({
        event_type: "$exposure",
        event_properties: { flag_key: flagKey, variant: value },
        // The user the server evaluated, if the root effect hasn't set it yet.
        ...(userId && !browserUserId ? { user_id: userId } : {}),
      });
    });
  }, [flagKey, deviceId, userId, value]);

  return variant;
}

export const TEMPLATES: string[] = ["blank", "kanban", "roadmap"];

// Replaces the version from /build/react-router-product-analytics, which rendered
// CreateProjectForm. No other React Router page adds lines here.
import { data } from "react-router";
import type { Route } from "./+types/new-project";
import { getUser } from "../auth.server";
import { loadFlags } from "../lib/flags.server";
import { useServerFlag } from "../lib/flags";
import { TEMPLATES } from "../lib/templates";
import { NewProjectForm } from "../components/NewProjectForm";

// Only flags this route renders. Every key here ends up in the page's
// serialized loader data, where anyone can read it in the page source.
const FLAG_KEYS = ["new-project-flow"];

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

export async function loader({ request }: Route.LoaderArgs) {
  const user = await getUser(request);
  const { flags, headers } = await loadFlags(request, user, FLAG_KEYS);
  return data({ amplitude: flags }, { headers });
}

// React Router sends a loader's Set-Cookie on its own, but no other loader
// header unless the route's headers export returns it.
export function headers({ loaderHeaders }: Route.HeadersArgs) {
  return loaderHeaders;
}

export default function NewProject({ loaderData }: Route.ComponentProps) {
  const variant = useServerFlag(loaderData.amplitude, "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 === "on" ? variant.payload : undefined) as
    | NewProjectPayload
    | undefined;
  const candidate = config?.defaultTemplate;
  const defaultTemplate =
    typeof candidate === "string" && TEMPLATES.includes(candidate) ? candidate : "blank";
  const showGallery = config?.showTemplateGallery === true;

  // The key recreates the form if a loader revalidation changes the variant.
  return (
    <NewProjectForm
      key={`${defaultTemplate}|${showGallery}`}
      defaultTemplate={defaultTemplate}
      showGallery={showGallery}
    />
  );
}

import { useState } from "react";
import * as amplitude from "@amplitude/unified";
import { TEMPLATES } from "../lib/templates";
import { ProjectChecklist } from "./ProjectChecklist";

type Props = { defaultTemplate: string; showGallery: boolean };

export function NewProjectForm({ defaultTemplate, showGallery }: Props) {
  // Seeded once, when the form is created.
  const [template, setTemplate] = useState(defaultTemplate);
  const [created, setCreated] = useState(false);

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

    amplitude.track("Project Created", { template });
    setCreated(true);
  }

  return (
    <>
      {showGallery ? (
        <fieldset>
          <legend>Start from a template</legend>
          {TEMPLATES.map((t) => (
            <label key={t}>
              <input
                type="radio"
                name="template"
                value={t}
                checked={template === t}
                onChange={() => setTemplate(t)}
              />
              {t}
            </label>
          ))}
        </fieldset>
      ) : (
        <select value={template} onChange={(e) => setTemplate(e.target.value)}>
          {TEMPLATES.map((t) => (
            <option key={t} value={t}>
              {t}
            </option>
          ))}
        </select>
      )}
      <button type="button" onClick={handleCreate}>
        Create project
      </button>

      {created ? <ProjectChecklist /> : null}
    </>
  );
}

import { useState, useSyncExternalStore } from "react";
// useEffect, amplitude, and amplitudeReady are already imported above.

type FetchUser = { user_properties?: Record<string, string> };

// Goes up by one each time a browser flag fetch settles. 0 means the
// first fetch hasn't settled yet.
let flagsVersion = 0;
let fetchGeneration = 0;
const listeners = new Set<() => void>();

function subscribe(listener: () => void) {
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

export async function refetchBrowserFlags(user?: FetchUser) {
  const generation = ++fetchGeneration;
  try {
    // experiment() is undefined until initAll has finished.
    if (await amplitudeReady) {
      // On failure or timeout the SDK returns and retries in the background.
      await amplitude.experiment()?.fetch(user);
    }
  } finally {
    // Only the newest fetch tells components to re-read, so a slow anonymous
    // fetch from page load doesn't re-render them after sign-in.
    if (generation === fetchGeneration) {
      flagsVersion += 1;
      listeners.forEach((listener) => listener());
    }
  }
}

export function useBrowserFlag(flagKey: string) {
  // The server snapshot is 0, so nothing reads a variant during server render.
  const version = useSyncExternalStore(subscribe, () => flagsVersion, () => 0);
  const [flag, setFlag] = useState<{ value: string | null; payload: unknown }>();

  // Runs after mount and whenever a fetch settles. variant() tracks an
  // exposure, so only components that show the variant call useBrowserFlag.
  useEffect(() => {
    if (version === 0) return;
    const variant = amplitude.experiment()?.variant(flagKey);
    setFlag({ value: variant?.value ?? null, payload: variant?.payload });
  }, [flagKey, version]);

  return { value: flag?.value ?? null, payload: flag?.payload };
}

import { useBrowserFlag } from "../lib/flags";

export function ProjectChecklist() {
  const checklist = useBrowserFlag("project-checklist");
  if (checklist.value !== "on") return null;

  return (
    <aside>
      <h2>Next steps</h2>
      <ul>
        <li>Invite your team</li>
        <li>Import your existing tasks</li>
      </ul>
    </aside>
  );
}

// Keep lines other React Router pages added here: the root loader and its imports
// (/build/react-router-product-analytics), useEngagementBridge() and <FeedbackButton />
// (/build/react-router-guides-surveys), and the <script> in Layout's head (/build/react-router-web-experiment).
// Add this import:
import { refetchBrowserFlags } from "./lib/flags";

export default function App({ loaderData }: Route.ComponentProps) {
  const id = loaderData.user?.id;
  const plan = loaderData.user?.plan ?? "unknown";

  // The root loader reruns after every action. Only act when the
  // identity actually changes.
  const lastIdentity = useRef<string | undefined>(undefined);

  useEffect(() => {
    const identity = id ? `user-${id}|${plan}` : "anonymous";
    if (identity === lastIdentity.current) return;
    lastIdentity.current = identity;

    if (!id) {
      // Anonymous: keep the device ID. Reset only from the sign-out handler.
      void refetchBrowserFlags();
      return;
    }

    // Amplitude drops IDs shorter than 5 characters. Same string as the server.
    amplitude.setUserId(`user-${id}`);
    const identify = new amplitude.Identify();
    identify.set("plan", plan);
    amplitude.identify(identify);
    // Pass plan with the request, so targeting sees it on this evaluation.
    void refetchBrowserFlags({ user_properties: { plan } });
  }, [id, plan]);

  return <Outlet />;
}

// Keep lines other React Router pages added here: the getEngagement import and
// getEngagement()?.gs.closeAll() before reset() (/build/react-router-guides-surveys).
// Order: closeAll, reset, clear.
import { Form } from "react-router";
import * as amplitude from "@amplitude/unified";

export function SignOutButton() {
  return (
    <Form
      method="post"
      action="/logout"
      onSubmit={() => {
        // Clears the user ID and issues a new device ID for the next person.
        amplitude.reset();
        // Drops the previous user's browser variants.
        amplitude.experiment()?.clear();
      }}
    >
      <button type="submit">Sign out</button>
    </Form>
  );
}

// -- .env --
VITE_AMPLITUDE_API_KEY=your-project-api-key
VITE_AMPLITUDE_DEPLOYMENT_KEY=your-client-deployment-key
AMPLITUDE_SERVER_DEPLOYMENT_KEY=your-server-deployment-key

// -- app/lib/experiment.server.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;
  user_properties?: Record<string, string>;
};

const store = globalThis as typeof globalThis & {
  __amplitudeFlags?: { client: LocalClient; ready: Promise<void> };
};

export function startFlags(): Promise<void> {
  if (!store.__amplitudeFlags) {
    const key = process.env.AMPLITUDE_SERVER_DEPLOYMENT_KEY;
    if (!key) return Promise.reject(new Error("AMPLITUDE_SERVER_DEPLOYMENT_KEY is not set"));
    const client = Experiment.initializeLocal(key);
    // react-router-serve closes its server on SIGTERM and SIGINT but doesn't
    // exit, and the flag poller would keep Node running. Stop it there.
    for (const signal of ["SIGTERM", "SIGINT"] as const) {
      if (process.listenerCount(signal) > 0) process.once(signal, () => client.stop());
    }
    const ready = client.start().catch((error) => {
      client.stop();
      if (store.__amplitudeFlags?.client === client) store.__amplitudeFlags = undefined;
      throw error;
    });
    store.__amplitudeFlags = { client, ready };
  }
  return store.__amplitudeFlags.ready;
}

export async function evaluateFlags(
  user: ExperimentUser,
  flagKeys: string[],
): Promise<ServerVariants> {
  if (!user.user_id && !user.device_id) return {};
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    const started = startFlags();
    const current = store.__amplitudeFlags?.client;
    await Promise.race([
      started,
      new Promise<never>((_, reject) => {
        timer = setTimeout(() => reject(new Error("flag rules not loaded within 1 s")), 1000);
      }),
    ]);
    return current ? current.evaluateV2(user, flagKeys) : {};
  } catch (error) {
    console.error("[flags] evaluation failed; rendering defaults.", error);
    return {};
  } finally {
    clearTimeout(timer);
  }
}

// -- app/lib/amplitude-cookies.ts --
export const DEVICE_ID_HANDOFF_COOKIE = "amp_server_device_id";

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isDeviceId(value: string | undefined): value is string {
  return value !== undefined && UUID.test(value);
}

export function readCookie(cookies: string, name: string): string | undefined {
  const prefix = `${name}=`;
  const match = cookies.split(/;\s*/).find((c) => c.startsWith(prefix));
  if (!match) return undefined;
  try {
    return decodeURIComponent(match.slice(prefix.length));
  } catch {
    return undefined;
  }
}

// -- app/lib/flags.server.ts --
import { randomUUID } from "node:crypto";
import { AmplitudeCookie } from "@amplitude/experiment-node-server";
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId, readCookie } from "./amplitude-cookies";
import type { ServerFlags } from "./flags";
import { evaluateFlags } from "./experiment.server";

type FlagUser = { id: string | number; plan?: string | null } | null;

function readDeviceId(cookies: string): string | undefined {
  const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;
  if (!apiKey) return undefined;
  try {
    const cookie = readCookie(cookies, AmplitudeCookie.cookieName(apiKey, true));
    return cookie ? (AmplitudeCookie.parse(cookie, true).device_id ?? undefined) : undefined;
  } catch {
    return undefined;
  }
}

export async function loadFlags(
  request: Request,
  user: FlagUser,
  flagKeys: string[],
): Promise<{ flags: ServerFlags; headers: Headers }> {
  const headers = new Headers({ "Cache-Control": "private, no-store" });
  const cookies = request.headers.get("Cookie") ?? "";

  let deviceId = readDeviceId(cookies);
  if (!deviceId) {
    const handoff = readCookie(cookies, DEVICE_ID_HANDOFF_COOKIE);
    if (isDeviceId(handoff)) deviceId = handoff;
  }
  if (!deviceId) {
    deviceId = randomUUID();
    headers.append(
      "Set-Cookie",
      `${DEVICE_ID_HANDOFF_COOKIE}=${deviceId}; Path=/; Max-Age=3600; SameSite=Lax`,
    );
  }

  const userId = user ? `user-${user.id}` : undefined;

  const variants = await evaluateFlags(
    {
      device_id: deviceId,
      user_id: userId,
      ...(user ? { user_properties: { plan: user.plan ?? "unknown" } } : {}),
    },
    flagKeys,
  );

  const flags: ServerFlags["flags"] = {};
  for (const [flagKey, variant] of Object.entries(variants)) {
    if (variant?.value && variant.value !== "off") {
      flags[flagKey] = { value: variant.value, payload: variant.payload };
    }
  }

  return { flags: { deviceId, userId, flags }, headers };
}

// -- app/lib/amplitude-ready.ts --
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

export function setAmplitudeReady(init: Promise<unknown> | null) {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error) => {
      console.warn("[amplitude] initAll failed", error);
      markReady(false);
    },
  );
}

// -- app/entry.client.tsx --
// Keep lines other React Router pages added here: pageViews: { trackHistoryChanges: "pathOnly" }
// (/build/react-router-web-analytics), debugMode and privacyConfig (/build/react-router-session-replay),
// the setAmplitudeReady(...) wrapper and setAmplitudeReady(null) (/build/react-router-guides-surveys),
// and the amplitude.add(webExperiment.plugin()) lines (/build/react-router-web-experiment).
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";
import * as amplitude from "@amplitude/unified";
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId, readCookie } from "./lib/amplitude-cookies";
import { setAmplitudeReady } from "./lib/amplitude-ready";

const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;

if (apiKey) {
  const hasAmpCookie = readCookie(document.cookie, `AMP_${apiKey.slice(0, 10)}`) !== undefined;
  const serverDeviceId = readCookie(document.cookie, DEVICE_ID_HANDOFF_COOKIE);
  const adoptServerDeviceId = !hasAmpCookie && isDeviceId(serverDeviceId);

  setAmplitudeReady(
    amplitude.initAll(apiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
        ...(adoptServerDeviceId ? { deviceId: serverDeviceId } : {}),
      },
      sessionReplay: {
        sampleRate: import.meta.env.DEV ? 1 : 0.01,
        debugMode: import.meta.env.DEV,
        privacyConfig: {
          maskSelector: ["[data-amp-mask]"],
          blockSelector: ["[data-amp-block]"],
          unmaskSelector: ["[data-amp-unmask]"],
        },
      },
      experiment: {
        deploymentKey: import.meta.env.VITE_AMPLITUDE_DEPLOYMENT_KEY,
        fetchTimeoutMillis: 3000,
      },
    }),
  );
} else {
  console.warn("VITE_AMPLITUDE_API_KEY is not set; analytics is off.");
  setAmplitudeReady(null);
}

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>
  );
});

// -- app/lib/flags.ts --
import { useEffect, useRef, useState, useSyncExternalStore } from "react";
import * as amplitude from "@amplitude/unified";
import { amplitudeReady } from "./amplitude-ready";

export type FlagVariant = { value: string; payload?: unknown };
export type ServerFlags = {
  deviceId: string;
  userId?: string;
  flags: Record<string, FlagVariant>;
};

export function useServerFlag(state: ServerFlags | null | undefined, flagKey: string) {
  const variant = state?.flags[flagKey];
  const value = variant?.value;
  const deviceId = state?.deviceId;
  const userId = state?.userId;
  const lastExposure = useRef<string | undefined>(undefined);

  useEffect(() => {
    if (!deviceId || !value) return;
    const key = `${userId ?? ""}|${deviceId}|${value}`;
    if (key === lastExposure.current) return;
    lastExposure.current = key;

    void amplitudeReady.then((ok) => {
      if (!ok) return;
      const browserDeviceId = amplitude.getDeviceId();
      const browserUserId = amplitude.getUserId();
      const sameDevice = browserDeviceId === deviceId;
      const sameUser = !userId || !browserUserId || browserUserId === userId;
      if (!sameDevice || !sameUser) {
        if (import.meta.env.DEV) {
          console.warn(
            `[flags] no exposure for ${flagKey}: the browser's device or user differs from what the server evaluated.`,
          );
        }
        return;
      }
      amplitude.track({
        event_type: "$exposure",
        event_properties: { flag_key: flagKey, variant: value },
        ...(userId && !browserUserId ? { user_id: userId } : {}),
      });
    });
  }, [flagKey, deviceId, userId, value]);

  return variant;
}

type FetchUser = { user_properties?: Record<string, string> };

let flagsVersion = 0;
let fetchGeneration = 0;
const listeners = new Set<() => void>();

function subscribe(listener: () => void) {
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

export async function refetchBrowserFlags(user?: FetchUser) {
  const generation = ++fetchGeneration;
  try {
    if (await amplitudeReady) {
      await amplitude.experiment()?.fetch(user);
    }
  } finally {
    if (generation === fetchGeneration) {
      flagsVersion += 1;
      listeners.forEach((listener) => listener());
    }
  }
}

export function useBrowserFlag(flagKey: string) {
  const version = useSyncExternalStore(subscribe, () => flagsVersion, () => 0);
  const [flag, setFlag] = useState<{ value: string | null; payload: unknown }>();

  useEffect(() => {
    if (version === 0) return;
    const variant = amplitude.experiment()?.variant(flagKey);
    setFlag({ value: variant?.value ?? null, payload: variant?.payload });
  }, [flagKey, version]);

  return { value: flag?.value ?? null, payload: flag?.payload };
}

// -- app/lib/templates.ts --
export const TEMPLATES: string[] = ["blank", "kanban", "roadmap"];

// -- app/routes/new-project.tsx --
// Replaces the version from /build/react-router-product-analytics, which rendered
// CreateProjectForm. No other React Router page adds lines here.
import { data } from "react-router";
import type { Route } from "./+types/new-project";
import { getUser } from "../auth.server";
import { loadFlags } from "../lib/flags.server";
import { useServerFlag } from "../lib/flags";
import { TEMPLATES } from "../lib/templates";
import { NewProjectForm } from "../components/NewProjectForm";

const FLAG_KEYS = ["new-project-flow"];

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

export async function loader({ request }: Route.LoaderArgs) {
  const user = await getUser(request);
  const { flags, headers } = await loadFlags(request, user, FLAG_KEYS);
  return data({ amplitude: flags }, { headers });
}

export function headers({ loaderHeaders }: Route.HeadersArgs) {
  return loaderHeaders;
}

export default function NewProject({ loaderData }: Route.ComponentProps) {
  const variant = useServerFlag(loaderData.amplitude, "new-project-flow");
  const config = (variant?.value === "on" ? variant.payload : undefined) as
    | NewProjectPayload
    | undefined;
  const candidate = config?.defaultTemplate;
  const defaultTemplate =
    typeof candidate === "string" && TEMPLATES.includes(candidate) ? candidate : "blank";
  const showGallery = config?.showTemplateGallery === true;

  return (
    <NewProjectForm
      key={`${defaultTemplate}|${showGallery}`}
      defaultTemplate={defaultTemplate}
      showGallery={showGallery}
    />
  );
}

// -- app/components/NewProjectForm.tsx --
import { useState } from "react";
import * as amplitude from "@amplitude/unified";
import { TEMPLATES } from "../lib/templates";
import { ProjectChecklist } from "./ProjectChecklist";

type Props = { defaultTemplate: string; showGallery: boolean };

export function NewProjectForm({ defaultTemplate, showGallery }: Props) {
  const [template, setTemplate] = useState(defaultTemplate);
  const [created, setCreated] = useState(false);

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

    amplitude.track("Project Created", { template });
    setCreated(true);
  }

  return (
    <>
      {showGallery ? (
        <fieldset>
          <legend>Start from a template</legend>
          {TEMPLATES.map((t) => (
            <label key={t}>
              <input
                type="radio"
                name="template"
                value={t}
                checked={template === t}
                onChange={() => setTemplate(t)}
              />
              {t}
            </label>
          ))}
        </fieldset>
      ) : (
        <select value={template} onChange={(e) => setTemplate(e.target.value)}>
          {TEMPLATES.map((t) => (
            <option key={t} value={t}>
              {t}
            </option>
          ))}
        </select>
      )}
      <button type="button" onClick={handleCreate}>
        Create project
      </button>
      {created ? <ProjectChecklist /> : null}
    </>
  );
}

// -- app/components/ProjectChecklist.tsx --
import { useBrowserFlag } from "../lib/flags";

export function ProjectChecklist() {
  const checklist = useBrowserFlag("project-checklist");
  if (checklist.value !== "on") return null;
  return (
    <aside>
      <h2>Next steps</h2>
      <ul>
        <li>Invite your team</li>
        <li>Import your existing tasks</li>
      </ul>
    </aside>
  );
}

// -- app/root.tsx (App export only; keep the template's imports, links, Layout and ErrorBoundary) --
// Keep lines other React Router pages added here: the root loader and its imports
// (/build/react-router-product-analytics), useEngagementBridge() and <FeedbackButton />
// (/build/react-router-guides-surveys), and the <script> in Layout's head (/build/react-router-web-experiment).
// Add this import:
import { refetchBrowserFlags } from "./lib/flags";

export default function App({ loaderData }: Route.ComponentProps) {
  const id = loaderData.user?.id;
  const plan = loaderData.user?.plan ?? "unknown";
  const lastIdentity = useRef<string | undefined>(undefined);

  useEffect(() => {
    const identity = id ? `user-${id}|${plan}` : "anonymous";
    if (identity === lastIdentity.current) return;
    lastIdentity.current = identity;
    if (!id) {
      void refetchBrowserFlags();
      return;
    }
    amplitude.setUserId(`user-${id}`);
    const identify = new amplitude.Identify();
    identify.set("plan", plan);
    amplitude.identify(identify);
    void refetchBrowserFlags({ user_properties: { plan } });
  }, [id, plan]);

  return <Outlet />;
}

// -- app/components/SignOutButton.tsx --
// Keep lines other React Router pages added here: the getEngagement import and
// getEngagement()?.gs.closeAll() before reset() (/build/react-router-guides-surveys).
// Order: closeAll, reset, clear.
import { Form } from "react-router";
import * as amplitude from "@amplitude/unified";

export function SignOutButton() {
  return (
    <Form
      method="post"
      action="/logout"
      onSubmit={() => {
        amplitude.reset();
        amplitude.experiment()?.clear();
      }}
    >
      <button type="submit">Sign out</button>
    </Form>
  );
}

Complete https://amplitude.com/build/react-router-product-analytics first, or
confirm this React Router framework mode app has its setup, including the
app/auth.server.ts stub and the projects/new route; create them if
missing. Then follow https://amplitude.com/build/react-router-feature-flags
exactly, using its Full code reference. I'll create the react-router-server and
web deployments and the new-project-flow (local) and project-checklist
(remote) flags; ask me for the keys. Put the server key in
AMPLITUDE_SERVER_DEPLOYMENT_KEY (no VITE_ prefix, read only in .server.ts
modules) and the client key in VITE_AMPLITUDE_DEPLOYMENT_KEY. Start the
local evaluation client lazily on the first evaluation, never at module
load, and wait at most 1000 ms before rendering defaults. The
new-project.tsx loader returns loadFlags' headers through a headers
export. Send $exposure from the browser only, and only when the browser's
device ID equals the server's and the user ID matches or is unset. Never
read a server-rendered flag with experiment().variant(), never call
reset() when the user is null, and never import a .server module into a
component. Merge into existing shared files (app/entry.client.tsx,
app/root.tsx, app/components/SignOutButton.tsx) and never delete lines
another Amplitude Build page added; each file's first comment names them.
Don't hardcode keys or invent flag or event names. Report every file you
changed.