🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(v4-migration): implement v4 migration UI toggle across settings page (#16151)
marliessophiea1556ff22ce8
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsxindex 2fc8337e10..43b9816880 100644--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx@@ -4,6 +4,7 @@ import { useHasEntitlement, usePlan } from "@/src/features/entitlements/hooks";import { useQueryProjectOrOrganization } from "@/src/features/projects/hooks";import { useHasOrganizationAccess } from "@/src/features/rbac/utils/checkOrganizationAccess";import { useIsCloudBillingAvailable } from "@/src/ee/features/billing/utils/isCloudBilling";+import { useV4UpgradeUiFlag } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";import { useOrganizationSettingsPages } from "@/src/pages/organization/[organizationId]/settings";vi.mock("@/src/components/PagedSettingsContainer", () => ({@@ -86,6 +87,10 @@ vi.mock("@/src/components/layouts/container-page", () => ({default: () => null,}));+vi.mock("@/src/features/v4-migration/useV4UpgradeUiEnabled", () => ({+ useV4UpgradeUiFlag: vi.fn(),+}));+const organization = {id: "org-1",name: "Org 1",@@ -103,6 +108,7 @@ describe("useOrganizationSettingsPages", () => {vi.mocked(useHasOrganizationAccess).mockReturnValue(false);vi.mocked(usePlan).mockReturnValue("oss");vi.mocked(useIsCloudBillingAvailable).mockReturnValue(false);+ vi.mocked(useV4UpgradeUiFlag).mockReturnValue(false);});it("hides organization API key settings without organization api key access", () => {@@ -137,4 +143,22 @@ describe("useOrganizationSettingsPages", () => {false,);});++ it("gates the v4 migration link on the v4UpgradeUi flag", () => {+ const { result } = renderHook(() => useOrganizationSettingsPages());++ expect(+ result.current.find((page) => page.slug === "v4-migration")?.show,+ ).toBe(false);++ vi.mocked(useV4UpgradeUiFlag).mockReturnValue(true);++ const { result: enabled } = renderHook(() =>+ useOrganizationSettingsPages(),+ );++ expect(+ enabled.current.find((page) => page.slug === "v4-migration")?.show,+ ).toBe(true);+ });});diff --git a/web/src/features/command-k-menu/CommandMenu.tsx b/web/src/features/command-k-menu/CommandMenu.tsxindex f3870c557c..88605ef929 100644--- a/web/src/features/command-k-menu/CommandMenu.tsx+++ b/web/src/features/command-k-menu/CommandMenu.tsx@@ -239,11 +239,13 @@ function AccountSettingsGroup({ onNavigate }: { onNavigate: () => void }) {const capture = usePostHogClientCapture();const accountSettingsPages = useAccountSettingsPages();- const accountSettingsItems = accountSettingsPages.map((page) => ({- title: `Account Settings > ${page.title}`,- url: `/account/settings${page.slug === "index" ? "" : `/${page.slug}`}`,- keywords: page.cmdKKeywords || [],- }));+ const accountSettingsItems = accountSettingsPages+ .filter((page) => !("href" in page))+ .map((page) => ({+ title: `Account Settings > ${page.title}`,+ url: `/account/settings${page.slug === "index" ? "" : `/${page.slug}`}`,+ keywords: page.cmdKKeywords || [],+ }));if (accountSettingsItems.length === 0) return null;diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsxindex cb148346e2..e911d68ab4 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx@@ -23,6 +23,8 @@ const mocks = vi.hoisted(() => ({// ready projects are hidden, so most cases need one open action item.evalCount: 1,lastTracePending: false,+ canToggleV4: true,+ isBetaEnabled: false,}));vi.mock("next/router", () => ({@@ -95,6 +97,18 @@ vi.mock("@/src/features/v4-migration/useV4UpgradeUiEnabled", () => ({useV4UpgradeUiEnabled: () => true,}));+vi.mock("@/src/features/events/hooks/useV4Beta", () => ({+ useV4Beta: () => ({+ canToggleV4: mocks.canToggleV4,+ isBetaEnabled: mocks.isBetaEnabled,+ }),+}));++// The toggle itself is covered where it lives; here we only assert placement.+vi.mock("@/src/features/events/components/V4SidebarToggle", () => ({+ V4PreviewToggleRow: () => <div data-testid="v4-preview-toggle-row" />,+}));+vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({useAccountV4MigrationData: () =>new Map([@@ -146,6 +160,8 @@ describe("V4MigrationStatusPage", () => {};mocks.evalCount = 1;mocks.lastTracePending = false;+ mocks.canToggleV4 = true;+ mocks.isBetaEnabled = false;});it("keeps the project table readable through horizontal scrolling", () => {@@ -233,6 +249,49 @@ describe("V4MigrationStatusPage", () => {).not.toBeInTheDocument();});+ it("offers v3 users a switch to the latest UI without a sunset note", () => {+ mocks.isBetaEnabled = false;++ render(<V4MigrationStatusPage />);++ expect(+ screen.getByText("Switch back to the latest UI (v4)"),+ ).toBeInTheDocument();+ expect(screen.getByTestId("v4-preview-toggle-row")).toBeInTheDocument();+ expect(+ screen.queryByText(/legacy v3 UI will be sunset/),+ ).not.toBeInTheDocument();+ });++ it("warns v4 users about the v3 sunset when offering the switch back", () => {+ mocks.isBetaEnabled = true;++ render(<V4MigrationStatusPage />);++ expect(+ screen.getByText("Need to switch back to the legacy UI (v3)?"),+ ).toBeInTheDocument();+ expect(+ screen.getByText(+ /The features powering the legacy v3 UI will be sunset on November 16, 2026\./,+ ),+ ).toBeInTheDocument();+ expect(screen.getByTestId("v4-preview-toggle-row")).toBeInTheDocument();+ });++ it("hides the switch-back section when the session cannot toggle v4", () => {+ mocks.canToggleV4 = false;++ render(<V4MigrationStatusPage />);++ expect(+ screen.queryByText("Switch back to the latest UI (v4)"),+ ).not.toBeInTheDocument();+ expect(+ screen.queryByTestId("v4-preview-toggle-row"),+ ).not.toBeInTheDocument();+ });+it("uses the November 16, 2026 deadline throughout the FAQ", () => {render(<V4MigrationStatusPage />);diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsxindex f4bf891ab7..39b0deb0d8 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx@@ -38,6 +38,8 @@ import {} from "@/src/features/v4-migration/migrationData";import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";import { V4MigrationLoadingState } from "@/src/features/v4-migration/V4MigrationLoadingState";+import { V4PreviewToggleRow } from "@/src/features/events/components/V4SidebarToggle";+import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";const V4_DOCS_URL = "https://langfuse.com/docs/v4";const SDK_UPGRADE_URL =@@ -676,7 +678,40 @@ function V4MigrationStatusPageContent() {</div></div></div>++ <SwitchBackSection /></div></ContainerPage>);}++// User-level v3/v4 UI toggle, the same one the migration side panel shows.+// Hides itself when the session cannot toggle v4 (legacy/events_only write+// mode, post-rollout auto-enrollment).+function SwitchBackSection() {+ const { canToggleV4, isBetaEnabled } = useV4Beta();++ if (!canToggleV4) {+ return null;+ }++ return (+ <div className="mt-6">+ <p className="text-base font-bold">+ {isBetaEnabled+ ? "Need to switch back to the legacy UI (v3)?"+ : "Switch back to the latest UI (v4)"}+ </p>+ <div className="flex flex-col gap-4 pt-4">+ {isBetaEnabled && (+ <p className="text-muted-foreground text-sm leading-relaxed">+ The features powering the legacy v3 UI will be sunset on{" "}+ {V4_MIGRATION_DEADLINE}. We strongly recommend switching to the+ latest UI (v4) before then.+ </p>+ )}+ <V4PreviewToggleRow />+ </div>+ </div>+ );+}diff --git a/web/src/pages/account/settings/index.tsx b/web/src/pages/account/settings/index.tsxindex 6bfe916953..dd4efd5228 100644--- a/web/src/pages/account/settings/index.tsx+++ b/web/src/pages/account/settings/index.tsx@@ -33,6 +33,7 @@ import { StringNoHTML } from "@langfuse/shared";import Link from "next/link";import { showSuccessToast } from "@/src/features/notifications/showSuccessToast";import { showErrorToast } from "@/src/features/notifications/showErrorToast";+import { useV4UpgradeUiFlag } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";const displayNameSchema = z.object({name: StringNoHTML.min(1, "Name cannot be empty").max(@@ -241,18 +242,25 @@ function DeleteAccountButton() {type AccountSettingsPage = {title: string;slug: string;- content: React.ReactNode;+ show?: boolean | (() => boolean);cmdKKeywords?: string[];-};+} & ({ content: React.ReactNode } | { href: string });export function useAccountSettingsPages(): AccountSettingsPage[] {const { data: session } = useSession();const userEmail = session?.user?.email ?? "";+ const showV4Migration = useV4UpgradeUiFlag();- return getAccountSettingsPages(userEmail);+ return getAccountSettingsPages({ userEmail, showV4Migration });}-const getAccountSettingsPages = (userEmail: string): AccountSettingsPage[] => [+const getAccountSettingsPages = ({+ userEmail,+ showV4Migration,+}: {+ userEmail: string;+ showV4Migration: boolean;+}): AccountSettingsPage[] => [{title: "General",slug: "index",@@ -304,14 +312,17 @@ const getAccountSettingsPages = (userEmail: string): AccountSettingsPage[] => [</div>),},+ {+ title: "v4 Migration",+ slug: "v4-migration",+ href: "/v4-migration",+ show: showV4Migration,+ },];export default function AccountSettingsPage() {- const { data: session } = useSession();const router = useRouter();- const userEmail = session?.user?.email ?? "";-- const pages = getAccountSettingsPages(userEmail);+ const pages = useAccountSettingsPages();return (<ContainerPagediff --git a/web/src/pages/organization/[organizationId]/settings/index.tsx b/web/src/pages/organization/[organizationId]/settings/index.tsxindex cee8218e46..1c9d492e6d 100644--- a/web/src/pages/organization/[organizationId]/settings/index.tsx+++ b/web/src/pages/organization/[organizationId]/settings/index.tsx@@ -20,6 +20,7 @@ import { useIsCloudBillingAvailable } from "@/src/ee/features/billing/utils/isClimport { env } from "@/src/env.mjs";import { OrgAuditLogsSettingsPage } from "@/src/ee/features/audit-log-viewer/OrgAuditLogsSettingsPage";import { useHasOrganizationAccess } from "@/src/features/rbac/utils/checkOrganizationAccess";+import { useV4UpgradeUiFlag } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";type OrganizationSettingsPage = {title: string;@@ -41,6 +42,7 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {const plan = usePlan();const isLangfuseCloud = isCloudPlan(plan) ?? false;const isCloudBillingAvailable = useIsCloudBillingAvailable();+ const showV4Migration = useV4UpgradeUiFlag();if (!organization) return [];@@ -50,6 +52,7 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {showOrgApiKeySettings,showAuditLogs,isLangfuseCloud,+ showV4Migration,});}@@ -59,12 +62,14 @@ export const getOrganizationSettingsPages = ({showOrgApiKeySettings,showAuditLogs,isLangfuseCloud,+ showV4Migration,}: {organization: { id: string; name: string; metadata: Record<string, unknown> };showBillingSettings: boolean;showOrgApiKeySettings: boolean;showAuditLogs: boolean;isLangfuseCloud: boolean;+ showV4Migration: boolean;}): OrganizationSettingsPage[] => [{title: "General",@@ -164,6 +169,12 @@ export const getOrganizationSettingsPages = ({slug: "projects",href: `/organization/${organization.id}`,},+ {+ title: "v4 Migration",+ slug: "v4-migration",+ href: "/v4-migration",+ show: showV4Migration,+ },];const OrgSettingsPage = () => {diff --git a/web/src/pages/project/[projectId]/settings/index.tsx b/web/src/pages/project/[projectId]/settings/index.tsxindex 5d87c6529b..6e11d95cb5 100644--- a/web/src/pages/project/[projectId]/settings/index.tsx+++ b/web/src/pages/project/[projectId]/settings/index.tsx@@ -34,6 +34,7 @@ import { PersonalNotificationSettings } from "@/src/features/notifications/compoimport { ProjectNotificationChannels } from "@/src/features/notifications/components/ProjectNotificationChannels";import { WebCalloutIntegrationCard } from "@/src/features/web-callouts/components/WebCalloutSettingsPage";import { DeveloperToolsSettings } from "@/src/features/developer-tools/components/DeveloperToolsSettings";+import { useV4UpgradeUiFlag } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";type ProjectSettingsPage = {title: string;@@ -50,6 +51,7 @@ export function useProjectSettingsPages(): ProjectSettingsPage[] {const showProtectedLabelsSettings = useHasEntitlement("prompt-protected-labels",);+ const showV4Migration = useV4UpgradeUiFlag();if (!project || !organization || !router.query.projectId) {return [];}@@ -61,6 +63,7 @@ export function useProjectSettingsPages(): ProjectSettingsPage[] {showRetentionSettings,showLLMConnectionsSettings: true,showProtectedLabelsSettings,+ showV4Migration,});}@@ -71,6 +74,7 @@ export const getProjectSettingsPages = ({showRetentionSettings,showLLMConnectionsSettings,showProtectedLabelsSettings,+ showV4Migration,}: {project: { id: string; name: string; metadata: Record<string, unknown> };organization: { id: string; name: string; metadata: Record<string, unknown> };@@ -78,6 +82,7 @@ export const getProjectSettingsPages = ({showRetentionSettings: boolean;showLLMConnectionsSettings: boolean;showProtectedLabelsSettings: boolean;+ showV4Migration: boolean;}): ProjectSettingsPage[] => [{title: "General",@@ -260,6 +265,12 @@ export const getProjectSettingsPages = ({slug: "organization",href: `/organization/${organization.id}/settings`,},+ {+ title: "v4 Migration",+ slug: "v4-migration",+ href: "/v4-migration",+ show: showV4Migration,+ },];export default function SettingsPage() {