Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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 (
<ContainerPage
diff --git a/web/src/pages/organization/[organizationId]/settings/index.tsx b/web/src/pages/organization/[organizationId]/settings/index.tsx
index 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/isCl
import { 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.tsx
index 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/compo
import { 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() {