Added URL overrides for Admin Labs flags (#30501)

ref https://linear.app/ghost/issue/BER-3920/

Allowed unreleased Admin features to be tested on live sites without changing
server-side Labs settings. Overrides are read from the labs query parameter,
persisted for the browser session, and synchronized with Ember during cold
loads so both Admin implementations use the same flag state.

Author: kevinansfield

apps/admin-x-framework/src/hooks/use-feature-flag.ts

@@ -1,11 +1,14 @@
 import { useBrowseConfig } from '../api/config';
+import { useFeatureFlagOverrides } from '../providers/feature-flag-overrides-context';
 
 /**
- * Returns whether a Labs flag is explicitly enabled. Only boolean `true`
- * counts — `false` while config is loading, missing, or failed.
- * Avoids refetching stale config when a feature-gated component mounts.
+ * Returns whether a Labs flag is explicitly enabled by config or the current
+ * session's URL overrides. Only boolean `true` config values count. Avoids
+ * refetching stale config when a feature-gated component mounts.
  */
 export const useFeatureFlag = (flag: string): boolean => {
   const { data: config } = useBrowseConfig({ refetchOnMount: false });
-  return config?.config.labs?.[flag] === true;
+  const { enabledFlags } = useFeatureFlagOverrides();
+
+  return config?.config.labs?.[flag] === true || enabledFlags.includes(flag);
 };

apps/admin-x-framework/src/providers/feature-flag-overrides-context.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+interface FeatureFlagOverridesContextValue {
+  enabledFlags: string[];
+}
+
+export const FeatureFlagOverridesContext = createContext<FeatureFlagOverridesContextValue>({
+  enabledFlags: [],
+});
+
+export const useFeatureFlagOverrides = () => useContext(FeatureFlagOverridesContext);

apps/admin-x-framework/src/providers/framework-provider.tsx

@@ -44,6 +44,8 @@ export interface FrameworkProviderProps {
   onUpdate: (dataType: string, response: unknown) => void;
   onInvalidate: (dataType: string) => void;
   onDelete: (dataType: string, id: string) => void;
+  // Called after URL overrides are synced to sessionStorage. May return cleanup work.
+  onFeatureFlagOverridesChange?: () => void | (() => void);
 
   // Optional QueryClient override. Defaults to the shared window-level
   // singleton; test harnesses pass a fresh client per render for isolation.

apps/admin-x-framework/src/providers/router-provider.tsx

@@ -12,6 +12,8 @@ import {
 import { useFramework } from './framework-provider';
 import { NavigationStackProvider } from './navigation-stack-provider';
 import { ErrorPage } from '@tryghost/shade/primitives';
+import { syncFeatureFlagOverrides } from '../utils/feature-flag-overrides';
+import { FeatureFlagOverridesContext } from './feature-flag-overrides-context';
 
 /**
  * This provider uses React Router to provide a router context to React apps
@@ -33,6 +35,23 @@ export interface RouterProviderProps {
   children?: React.ReactNode;
 }
 
+function FeatureFlagOverridesRouteProvider({ children }: { children: React.ReactNode }) {
+  const { search } = useLocation();
+  const { onFeatureFlagOverridesChange } = useFramework();
+  const enabledFlags = useMemo(() => syncFeatureFlagOverrides(search), [search]);
+  const value = useMemo(() => ({ enabledFlags }), [enabledFlags]);
+
+  useEffect(() => {
+    return onFeatureFlagOverridesChange?.();
+  }, [enabledFlags, onFeatureFlagOverridesChange]);
+
+  return (
+    <FeatureFlagOverridesContext.Provider value={value}>
+      {children}
+    </FeatureFlagOverridesContext.Provider>
+  );
+}
+
 // Store scroll positions globally
 const scrollPositions = new Map<string, number>();
 
@@ -100,7 +119,11 @@ export function RouterProvider({ routes, prefix, errorElement, children }: Route
     // Create a root route that wraps all routes with NavigationStackProvider
     // and any additional children (providers) so they have access to routing
     const rootRoute: RouteObject = {
-      element: <NavigationStackProvider>{children}</NavigationStackProvider>,
+      element: (
+        <FeatureFlagOverridesRouteProvider>
+          <NavigationStackProvider>{children}</NavigationStackProvider>
+        </FeatureFlagOverridesRouteProvider>
+      ),
       hydrateFallbackElement: <></>,
       children: routes.map((route) => ({
         ...route,

apps/admin-x-framework/src/utils/feature-flag-overrides.ts

@@ -0,0 +1,46 @@
+const LABS_QUERY_PARAM = 'labs';
+const LABS_STORAGE_KEY = 'ghost-admin:labs-overrides';
+
+const getUrlFeatureFlags = (searchParams: URLSearchParams): string[] => {
+  return searchParams
+    .getAll(LABS_QUERY_PARAM)
+    .flatMap((value) => value.split(','))
+    .filter(Boolean);
+};
+
+export const getStoredFeatureFlagOverrides = (): string[] => {
+  try {
+    const storedFlags: unknown = JSON.parse(sessionStorage.getItem(LABS_STORAGE_KEY) ?? '[]');
+
+    if (!Array.isArray(storedFlags)) {
+      return [];
+    }
+
+    return storedFlags.filter((flag): flag is string => typeof flag === 'string');
+  } catch {
+    return [];
+  }
+};
+
+export const syncFeatureFlagOverrides = (search: string): string[] => {
+  const searchParams = new URLSearchParams(search);
+
+  if (!searchParams.has(LABS_QUERY_PARAM)) {
+    return getStoredFeatureFlagOverrides();
+  }
+
+  const flags = getUrlFeatureFlags(searchParams);
+
+  try {
+    if (flags.length > 0) {
+      sessionStorage.setItem(LABS_STORAGE_KEY, JSON.stringify(flags));
+    } else {
+      sessionStorage.removeItem(LABS_STORAGE_KEY);
+    }
+  } catch {
+    // Storage can be unavailable in restricted browser environments. The URL
+    // override still applies to the current React render in that case.
+  }
+
+  return flags;
+};

apps/admin-x-framework/test/unit/hooks/use-feature-flag.test.ts

@@ -4,10 +4,15 @@ import { useFeatureFlag } from '../../../src/hooks/use-feature-flag';
 vi.mock('../../../src/api/config', () => ({
   useBrowseConfig: vi.fn(),
 }));
+vi.mock('../../../src/providers/feature-flag-overrides-context', () => ({
+  useFeatureFlagOverrides: vi.fn(),
+}));
 
 import { useBrowseConfig } from '../../../src/api/config';
+import { useFeatureFlagOverrides } from '../../../src/providers/feature-flag-overrides-context';
 
 const mockUseBrowseConfig = useBrowseConfig as any;
+const mockUseFeatureFlagOverrides = vi.mocked(useFeatureFlagOverrides);
 
 const withLabs = (labs: Record<string, unknown>) => ({
   data: { config: { labs } },
@@ -16,6 +21,7 @@ const withLabs = (labs: Record<string, unknown>) => ({
 describe('useFeatureFlag', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mockUseFeatureFlagOverrides.mockReturnValue({ enabledFlags: [] });
   });
 
   it('returns true when the flag is explicitly true', () => {
@@ -65,4 +71,22 @@ describe('useFeatureFlag', () => {
 
     expect(result.current).toBe(false);
   });
+
+  it('enables a flag when the session override enables it', () => {
+    mockUseBrowseConfig.mockReturnValue(withLabs({ myFlag: false }));
+    mockUseFeatureFlagOverrides.mockReturnValue({ enabledFlags: ['myFlag'] });
+
+    const { result } = renderHook(() => useFeatureFlag('myFlag'));
+
+    expect(result.current).toBe(true);
+  });
+
+  it('returns false when the session override does not enable the flag', () => {
+    mockUseBrowseConfig.mockReturnValue(withLabs({ myFlag: false }));
+    mockUseFeatureFlagOverrides.mockReturnValue({ enabledFlags: ['otherFlag'] });
+
+    const { result } = renderHook(() => useFeatureFlag('myFlag'));
+
+    expect(result.current).toBe(false);
+  });
 });

apps/admin-x-framework/test/unit/providers/router-provider.test.tsx

@@ -1,8 +1,35 @@
 import { StrictMode } from 'react';
 import { render, waitFor } from '@testing-library/react';
-import { Navigate } from '../../../src/providers/router-provider';
+import { Navigate, RouterProvider } from '../../../src/providers/router-provider';
 import { TestWrapper } from '../../../src/test/test-utils';
 
+describe('feature flag overrides', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    window.location.hash = '';
+  });
+
+  afterEach(() => {
+    sessionStorage.clear();
+    window.location.hash = '';
+  });
+
+  it('notifies the host after storing URL overrides', async () => {
+    window.location.hash = '#/?labs=testFlag';
+    const onFeatureFlagOverridesChange = vi.fn(() => {
+      expect(sessionStorage.getItem('ghost-admin:labs-overrides')).toBe('["testFlag"]');
+    });
+
+    render(
+      <TestWrapper frameworkProps={{ onFeatureFlagOverridesChange }}>
+        <RouterProvider prefix="/" routes={[{ path: '/', element: <div>Home</div> }]} />
+      </TestWrapper>,
+    );
+
+    await waitFor(() => expect(onFeatureFlagOverridesChange).toHaveBeenCalled());
+  });
+});
+
 describe('Navigate', () => {
   it('performs cross-app navigation once after mounting in Strict Mode', async () => {
     const externalNavigate = vi.fn();

apps/admin-x-framework/test/unit/utils/feature-flag-overrides.test.ts

@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import {
+  getStoredFeatureFlagOverrides,
+  syncFeatureFlagOverrides,
+} from '../../../src/utils/feature-flag-overrides';
+
+describe('feature flag overrides', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+  });
+
+  it('stores flags listed in the labs query parameter', () => {
+    expect(syncFeatureFlagOverrides('?labs=testFlag,secondFlag')).toEqual([
+      'testFlag',
+      'secondFlag',
+    ]);
+    expect(getStoredFeatureFlagOverrides()).toEqual(['testFlag', 'secondFlag']);
+  });
+
+  it('supports repeated labs query parameters', () => {
+    expect(syncFeatureFlagOverrides('?labs=testFlag&labs=secondFlag')).toEqual([
+      'testFlag',
+      'secondFlag',
+    ]);
+  });
+
+  it('uses stored overrides when the URL has no labs parameter', () => {
+    syncFeatureFlagOverrides('?labs=testFlag');
+
+    expect(syncFeatureFlagOverrides('?page=2')).toEqual(['testFlag']);
+  });
+
+  it('replaces stored overrides when the URL specifies new flags', () => {
+    syncFeatureFlagOverrides('?labs=testFlag');
+
+    expect(syncFeatureFlagOverrides('?labs=secondFlag')).toEqual(['secondFlag']);
+    expect(getStoredFeatureFlagOverrides()).toEqual(['secondFlag']);
+  });
+
+  it('clears stored overrides for an empty labs parameter', () => {
+    syncFeatureFlagOverrides('?labs=testFlag');
+
+    expect(syncFeatureFlagOverrides('?labs=')).toEqual([]);
+    expect(getStoredFeatureFlagOverrides()).toEqual([]);
+  });
+
+  it('ignores malformed stored overrides', () => {
+    sessionStorage.setItem('ghost-admin:labs-overrides', '{invalid');
+
+    expect(getStoredFeatureFlagOverrides()).toEqual([]);
+  });
+});

apps/admin/src/ember-bridge/ember-bridge.test.tsx

@@ -44,6 +44,7 @@ function createMockStateBridge(sidebarVisible = true) {
     onUpdate: vi.fn(),
     onInvalidate: vi.fn(),
     onDelete: vi.fn(),
+    refreshFeatureFlagOverrides: vi.fn(),
     isFeatureEnabled: vi.fn().mockReturnValue(false),
     on,
     off,
@@ -638,6 +639,22 @@ describe('theme bridge helpers', () => {
 });
 
 describe('emberMutationHandlers', () => {
+  test('waits for Ember to load before refreshing feature flag overrides', async () => {
+    vi.useFakeTimers();
+    const { emberMutationHandlers } = await import('./ember-bridge');
+
+    const stopWaiting = emberMutationHandlers.onFeatureFlagOverridesChange();
+    const mock = createMockStateBridge();
+    window.EmberBridge = { state: mock.stateBridge };
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    expect(mock.stateBridge.refreshFeatureFlagOverrides).toHaveBeenCalledTimes(1);
+    stopWaiting();
+  });
+
   test('resolves the bridge at call time, not import time', async () => {
     // Import first, install the bridge after: forwarding must still work.
     const { emberMutationHandlers } = await import('./ember-bridge');

apps/admin/src/ember-bridge/ember-bridge.tsx

@@ -23,6 +23,7 @@ export interface StateBridge {
   onUpdate: (dataType: string, response: unknown) => void;
   onInvalidate: (dataType: string) => void;
   onDelete: (dataType: string, id: string) => void;
+  refreshFeatureFlagOverrides?: () => void;
   isFeatureEnabled?: (name: string) => boolean | undefined;
   preloadAdminThemeStylesheet?: () => Promise<void>;
   applyAdminThemePreference?: (mode: AdminThemeMode) => Promise<void> | void;
@@ -315,11 +316,15 @@ export function applyEmberAdminThemePreference(mode: AdminThemeMode): boolean {
 }
 
 /**
- * React -> Ember mutation sync handlers for the FrameworkProvider. Each
- * forwards a successful React mutation to Ember's store sync and no-ops when
- * the bridge is absent (standalone React).
+ * React -> Ember handlers for the FrameworkProvider. Feature flag overrides
+ * wait for Ember to load; mutation handlers no-op when the bridge is absent.
  */
 export const emberMutationHandlers = {
+  onFeatureFlagOverridesChange: (): (() => void) => {
+    return waitForStateBridge((stateBridge) => {
+      stateBridge.refreshFeatureFlagOverrides?.();
+    });
+  },
   onUpdate: (dataType: string, response: unknown): void => {
     window.EmberBridge?.state.onUpdate(dataType, response);
   },