Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

feat: warn when the SDK host app runs React 18 (#82432)

Mahatthana (Kelvin) Nomsawadi0cf4271e3320
diff --git a/e2e/test-component/scenarios/embedding-sdk/react-18-deprecation-warning.cy.spec.tsx b/e2e/test-component/scenarios/embedding-sdk/react-18-deprecation-warning.cy.spec.tsx
new file mode 100644
index 00000000000..2a1d7ad2fe1
--- /dev/null
+++ b/e2e/test-component/scenarios/embedding-sdk/react-18-deprecation-warning.cy.spec.tsx
@@ -0,0 +1,66 @@
+import { StaticQuestion } from "@metabase/embedding-sdk-react";
+import { version as reactVersion } from "react";
+
+import { ORDERS_QUESTION_ID } from "e2e/support/cypress_sample_instance_data";
+import { getSdkRoot } from "e2e/support/helpers/e2e-embedding-sdk-helpers";
+import { mountSdkContent } from "e2e/support/helpers/embedding-sdk-component-testing";
+import { signInAsAdminAndEnableEmbeddingSdk } from "e2e/support/helpers/embedding-sdk-testing";
+import { mockAuthProviderAndJwtSignIn } from "e2e/support/helpers/embedding-sdk-testing/embedding-sdk-helpers";
+
+// In .github/workflows/embedding-sdk-component-tests.yml, we run tests
+// across multiple React versions, including React 19.
+const hostReactMajorVersion = parseInt(reactVersion, 10);
+
+const REACT_18_WARNING =
+ "This application uses React 18. The Metabase modular embedding SDK will require React 19 in a future release, and this embed will stop working once your Metabase instance is upgraded to it. Please upgrade your application to React 19.";
+
+describe("scenarios > embedding-sdk > react-18-deprecation-warning", () => {
+ beforeEach(() => {
+ signInAsAdminAndEnableEmbeddingSdk();
+
+ cy.signOut();
+
+ mockAuthProviderAndJwtSignIn();
+
+ cy.window().then((win) => {
+ cy.spy(win.console, "warn").as("consoleWarn");
+ });
+ });
+
+ (hostReactMajorVersion === 18 ? it : it.skip)(
+ "warns about React 18 on localhost when the host app runs React 18",
+ () => {
+ mountSdkContent(<StaticQuestion questionId={ORDERS_QUESTION_ID} />);
+
+ getSdkRoot().findByText("Product ID").should("exist");
+
+ cy.findByTestId("sdk-usage-problem-indicator").click();
+
+ cy.findByTestId("sdk-usage-problem-card").should(
+ "contain.text",
+ REACT_18_WARNING,
+ );
+
+ cy.get("@consoleWarn").should(
+ "have.been.calledWithMatch",
+ REACT_18_WARNING,
+ );
+ },
+ );
+
+ (hostReactMajorVersion > 18 ? it : it.skip)(
+ "does not warn about React 18 when the host app runs a newer React",
+ () => {
+ mountSdkContent(<StaticQuestion questionId={ORDERS_QUESTION_ID} />);
+
+ getSdkRoot().findByText("Product ID").should("exist");
+
+ cy.findByTestId("sdk-usage-problem-indicator").should("not.exist");
+
+ cy.get("@consoleWarn").should(
+ "not.have.been.calledWithMatch",
+ REACT_18_WARNING,
+ );
+ },
+ );
+});
diff --git a/enterprise/frontend/src/embedding-sdk-ee/tests/auth-flow/jwt.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-ee/tests/auth-flow/jwt.unit.spec.tsx
index 15e363eda5a..81dfeb5ca80 100644
--- a/enterprise/frontend/src/embedding-sdk-ee/tests/auth-flow/jwt.unit.spec.tsx
+++ b/enterprise/frontend/src/embedding-sdk-ee/tests/auth-flow/jwt.unit.spec.tsx
@@ -24,6 +24,12 @@ import { setupEmbeddingSdkEnterprisePlugins } from "../support";
import { setup as baseSetup } from "./setup";
+// Jest runs React 18 on localhost, which shows the React 18 warning banner.
+// Mock React 19 so the spec only sees the usage problems it tests.
+jest.mock("embedding-sdk-bundle/lib/host-react-version", () => ({
+ getHostReactMajorVersion: () => 19,
+}));
+
const setup = ({
authConfig,
locale,
diff --git a/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay-simple-embedding.unit.spec.tsx b/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay-simple-embedding.unit.spec.tsx
index ed496859d0e..1de8723bbc7 100644
--- a/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay-simple-embedding.unit.spec.tsx
+++ b/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay-simple-embedding.unit.spec.tsx
@@ -8,6 +8,7 @@ import { mockSettings } from "__support__/settings";
import { createMockState } from "__support__/state";
import { screen, within } from "__support__/ui";
import * as IsLocalhostModule from "embedding-sdk-bundle/lib/get-is-localhost";
+import { getHostReactMajorVersion } from "embedding-sdk-bundle/lib/host-react-version";
import { renderWithSDKProviders } from "embedding-sdk-bundle/test/__support__/ui";
import { createMockSdkConfig } from "embedding-sdk-bundle/test/mocks/config";
import {
@@ -26,8 +27,16 @@ jest.mock("metabase/visualizations/register", () => ({
registerVisualizations: jest.fn(),
}));
+// Jest runs React 18 on localhost, which shows the React 18 warning banner.
+// Each test sets the host React major version instead.
+jest.mock("embedding-sdk-bundle/lib/host-react-version", () => ({
+ getHostReactMajorVersion: jest.fn(),
+}));
+
jest.mock("metabase/embedding-sdk/config", () => ({
...jest.requireActual("metabase/embedding-sdk/config"),
+ // The actual helper reads the actual config, not the mocked one below.
+ isEmbeddingEajs: () => true,
EMBEDDING_SDK_CONFIG: {
isEmbeddingSdk: true,
metabaseClientRequestHeader: "embedding-simple",
@@ -43,9 +52,12 @@ jest.mock("metabase/embedding-sdk/config", () => ({
interface Options {
hasSimpleEmbeddingFeature?: boolean;
isSimpleEmbeddingEnabled?: boolean;
+ hostReactMajorVersion?: number;
}
-const setup = (options: Options) => {
+const setup = ({ hostReactMajorVersion = 19, ...options }: Options) => {
+ jest.mocked(getHostReactMajorVersion).mockReturnValue(hostReactMajorVersion);
+
const tokenFeatures = createMockTokenFeatures({
embedding_simple: options.hasSimpleEmbeddingFeature ?? true,
});
@@ -156,4 +168,14 @@ describe("SdkUsageProblemDisplay (simple embedding)", () => {
mock.mockRestore();
});
+
+ it("does not show the React 18 warning, since the iframe embed runs the React shipped by Metabase", async () => {
+ expect(window.location.origin).toBe("http://localhost");
+
+ await setup({ hostReactMajorVersion: 18 });
+
+ expect(
+ screen.queryByTestId(PROBLEM_INDICATOR_TEST_ID),
+ ).not.toBeInTheDocument();
+ });
});
diff --git a/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay.unit.spec.tsx b/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay.unit.spec.tsx
index b4f717589ec..776c4f78219 100644
--- a/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay.unit.spec.tsx
+++ b/frontend/src/embedding-sdk-bundle/components/private/SdkUsageProblem/SdkUsageProblemDisplay.unit.spec.tsx
@@ -1,4 +1,5 @@
import userEvent from "@testing-library/user-event";
+import type { ReactElement } from "react";
import {
setupPropertiesEndpoints,
@@ -6,18 +7,24 @@ import {
} from "__support__/server-mocks";
import { mockSettings } from "__support__/settings";
import { createMockState } from "__support__/state";
-import { screen, waitFor, within } from "__support__/ui";
+import { act, screen, waitFor, within } from "__support__/ui";
+import { SdkUsageProblemDisplay } from "embedding-sdk-bundle/components/private/SdkUsageProblem";
import * as IsLocalhostModule from "embedding-sdk-bundle/lib/get-is-localhost";
+import { getHostReactMajorVersion } from "embedding-sdk-bundle/lib/host-react-version";
+import { initAuth } from "embedding-sdk-bundle/store/auth";
import { renderWithSDKProviders } from "embedding-sdk-bundle/test/__support__/ui";
import {
createMockApiKeyConfig,
createMockSdkConfig,
} from "embedding-sdk-bundle/test/mocks/config";
import {
+ createMockLoginStatusState,
createMockSdkState,
createMockTokenState,
} from "embedding-sdk-bundle/test/mocks/state";
import type { MetabaseAuthConfig } from "embedding-sdk-bundle/types";
+import type { LoginStatus } from "embedding-sdk-bundle/types/user";
+import * as IsHostAppInDevModeModule from "embedding-sdk-shared/lib/is-host-app-in-dev-mode";
import {
createMockSettings,
createMockTokenFeatures,
@@ -30,15 +37,32 @@ jest.mock("metabase/visualizations/register", () => ({
registerVisualizations: jest.fn(),
}));
+// Jest runs React 18 on localhost, which shows the React 18 warning banner.
+// Each test sets the host React major version instead.
+jest.mock("embedding-sdk-bundle/lib/host-react-version", () => ({
+ getHostReactMajorVersion: jest.fn(),
+}));
+
interface Options {
authConfig: MetabaseAuthConfig;
hasEmbeddingFeature?: boolean;
isEmbeddingSdkEnabled?: boolean;
isDevelopmentMode?: boolean;
hasExpirationClaim?: boolean;
+ hostReactMajorVersion?: number;
+ initStatus?: LoginStatus["status"];
+ children?: ReactElement;
}
-const setup = ({ hasExpirationClaim = true, ...options }: Options) => {
+const setup = ({
+ hasExpirationClaim = true,
+ hostReactMajorVersion = 19,
+ initStatus = "success",
+ children = <div>hello!</div>,
+ ...options
+}: Options) => {
+ jest.mocked(getHostReactMajorVersion).mockReturnValue(hostReactMajorVersion);
+
const tokenFeatures = createMockTokenFeatures({
embedding_sdk: options.hasEmbeddingFeature ?? true,
development_mode: options.isDevelopmentMode ?? false,
@@ -54,6 +78,7 @@ const setup = ({ hasExpirationClaim = true, ...options }: Options) => {
settings: mockSettings(settingValues),
currentUser: TEST_USER,
sdk: createMockSdkState({
+ initStatus: createMockLoginStatusState({ status: initStatus }),
token: createMockTokenState({
token: {
id: "123",
@@ -68,7 +93,7 @@ const setup = ({ hasExpirationClaim = true, ...options }: Options) => {
setupSettingsEndpoints([]);
setupPropertiesEndpoints(settingValues);
- return renderWithSDKProviders(<div>hello!</div>, {
+ return renderWithSDKProviders(children, {
componentProviderProps: { authConfig: options.authConfig },
storeInitialState: state,
});
@@ -313,6 +338,217 @@ describe("SdkUsageProblemDisplay", () => {
);
});
+ it("shows a warning when the host app runs React 18 on localhost", async () => {
+ expect(window.location.origin).toBe("http://localhost");
+
+ setup({ authConfig: createMockSdkConfig(), hostReactMajorVersion: 18 });
+
+ await userEvent.click(screen.getByTestId(PROBLEM_INDICATOR_TEST_ID));
+
+ const card = screen.getByTestId(PROBLEM_CARD_TEST_ID);
+
+ expect(
+ within(card).getByText("This embed is powered by the Metabase SDK."),
+ ).toBeInTheDocument();
+
+ expect(
+ within(card).getByText(
+ "This application uses React 18. The Metabase modular embedding SDK will require React 19 in a future release, and this embed will stop working once your Metabase instance is upgraded to it. Please upgrade your application to React 19.",
+ ),
+ ).toBeInTheDocument();
+
+ const docsLink = within(card).getByRole("link", {
+ name: "Documentation",
+ });
+
+ expect(docsLink).toHaveAttribute(
+ "href",
+ "https://www.metabase.com/docs/latest/embedding/sdk/introduction#modular-embedding-sdk-prerequisites",
+ );
+ });
+
+ it("logs a usage problem to the console once the SDK has initialized", async () => {
+ const consoleWarnSpy = jest
+ .spyOn(console, "warn")
+ .mockImplementation(() => {});
+ const authConfig = createMockSdkConfig();
+
+ // The SDK test renderer turns console logging off for its own display.
+ const { store } = setup({
+ authConfig,
+ hostReactMajorVersion: 18,
+ initStatus: "loading",
+ children: (
+ <SdkUsageProblemDisplay authConfig={authConfig} allowConsoleLog />
+ ),
+ });
+
+ expect(
+ await screen.findAllByTestId(PROBLEM_INDICATOR_TEST_ID),
+ ).not.toHaveLength(0);
+ expect(consoleWarnSpy).not.toHaveBeenCalled();
+
+ act(() => {
+ store.dispatch(initAuth.fulfilled(undefined, "test-request", authConfig));
+ });
+
+ await waitFor(() => {
+ expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+ });
+ expect(String(consoleWarnSpy.mock.calls[0][0])).toContain(
+ "This application uses React 18. The Metabase modular embedding SDK will require React 19 in a future release, and this embed will stop working once your Metabase instance is upgraded to it. Please upgrade your application to React 19.",
+ );
+
+ consoleWarnSpy.mockRestore();
+ });
+
+ it("does not show the React 18 warning outside localhost", () => {
+ const mock = jest
+ .spyOn(IsLocalhostModule, "getIsLocalhost")
+ .mockImplementation(() => false);
+
+ setup({ authConfig: createMockSdkConfig(), hostReactMajorVersion: 18 });
+
+ expect(
+ screen.queryByTestId(PROBLEM_INDICATOR_TEST_ID),
+ ).not.toBeInTheDocument();
+
+ mock.mockRestore();
+ });
+
+ it("does not show the React 18 warning when the host app runs React 19", () => {
+ setup({ authConfig: createMockSdkConfig(), hostReactMajorVersion: 19 });
+
+ expect(
+ screen.queryByTestId(PROBLEM_INDICATOR_TEST_ID),
+ ).not.toBeInTheDocument();
+ });
+
+ it("shows the React 18 warning over the API key warning on localhost", async () => {
+ setup({ authConfig: createMockApiKeyConfig(), hostReactMajorVersion: 18 });
+
+ await userEvent.click(screen.getByTestId(PROBLEM_INDICATOR_TEST_ID));
+
+ const card = screen.getByTestId(PROBLEM_CARD_TEST_ID);
+
+ expect(
+ within(card).getByText(
+ "This application uses React 18. The Metabase modular embedding SDK will require React 19 in a future release, and this embed will stop working once your Metabase instance is upgraded to it. Please upgrade your application to React 19.",
+ ),
+ ).toBeInTheDocument();
+
+ expect(
+ within(card).queryByText(
+ /This is intended for evaluation purposes and works only on localhost. To use on other sites, implement SSO./,
+ ),
+ ).not.toBeInTheDocument();
+ });
+
+ it("shows the React 18 warning on a non-localhost host app in development mode", async () => {
+ const isLocalhostMock = jest
+ .spyOn(IsLocalhostModule, "getIsLocalhost")
+ .mockImplementation(() => false);
+ const isHostAppInDevModeMock = jest
+ .spyOn(IsHostAppInDevModeModule, "isHostAppInDevMode")
+ .mockImplementation(() => true);
+
+ setup({ authConfig: createMockSdkConfig(), hostReactMajorVersion: 18 });
+
+ await userEvent.click(screen.getByTestId(PROBLEM_INDICATOR_TEST_ID));
+
+ expect(
+ within(screen.getByTestId(PROBLEM_CARD_TEST_ID)).getByText(
+ "This application uses React 18. The Metabase modular embedding SDK will require React 19 in a future release, and this embed will stop working once your Metabase instance is upgraded to it. Please upgrade your application to React 19.",
+ ),
+ ).toBeInTheDocument();
+
+ isLocalhostMock.mockRestore();
+ isHostAppInDevModeMock.mockRestore();
+ });
+
+ it("shows the license error over the React 18 warning when JWT is used without a license", async () => {
+ setup({
+ authConfig: createMockSdkConfig(),
+ hasEmbeddingFeature: false,
+ hostReactMajorVersion: 18,
+ });
+
+ await userEvent.click(screen.getByTestId(PROBLEM_INDICATOR_TEST_ID));
+
+ const card = screen.getByTestId(PROBLEM_CARD_TEST_ID);
+
+ expect(
+ within(card).getByText(
+ "Usage without a valid license for this feature is only allowed for evaluation purposes, using API keys and only on localhost. Attempting to use this in other ways is in breach of our usage policy.",
+ ),
+ ).toBeInTheDocument();
+
+ expect(
+ within(card).queryByText(/This application uses React 18/),
+ ).not.toBeInTheDocument();
+ });
+
+ it("shows the SDK disabled error over the React 18 warning on a host app in development mode", async () => {
+ const isLocalhostMock = jest
+ .spyOn(IsLocalhostModule, "getIsLocalhost")
+ .mockImplementation(() => false);
+ const isHostAppInDevModeMock = jest
+ .spyOn(IsHostAppInDevModeModule, "isHostAppInDevMode")
+ .mockImplementation(() => true);
+
+ setup({
+ authConfig: createMockSdkConfig(),
+ isEmbeddingSdkEnabled: false,
+ hostReactMajorVersion: 18,
+ });
+
+ await userEvent.click(screen.getByTestId(PROBLEM_INDICATOR_TEST_ID));
+
+ const card = screen.getByTestId(PROBLEM_CARD_TEST_ID);
+
+ expect(
+ within(card).getByText(
+ "Embedding is not enabled for this instance. Please enable it in settings.",
+ ),
+ ).toBeInTheDocument();
+
+ expect(
+ within(card).queryByText(/This application uses React 18/),
+ ).not.toBeInTheDocument();
+
+ isLocalhostMock.mockRestore();
+ isHostAppInDevModeMock.mockRestore();
+ });
+
+ it("shows the API key error over the React 18 warning on a non-localhost host app in development mode", async () => {
+ const isLocalhostMock = jest
+ .spyOn(IsLocalhostModule, "getIsLocalhost")
+ .mockImplementation(() => false);
+ const isHostAppInDevModeMock = jest
+ .spyOn(IsHostAppInDevModeModule, "isHostAppInDevMode")
+ .mockImplementation(() => true);
+
+ setup({ authConfig: createMockApiKeyConfig(), hostReactMajorVersion: 18 });
+
+ await userEvent.click(screen.getByTestId(PROBLEM_INDICATOR_TEST_ID));
+
+ const card = screen.getByTestId(PROBLEM_CARD_TEST_ID);
+
+ expect(within(card).getByText("Error")).toBeInTheDocument();
+ expect(
+ within(card).getByText(
+ "This embed is using API keys. This is intended for evaluation purposes and works only on localhost. To use on other sites, implement SSO.",
+ ),
+ ).toBeInTheDocument();
+
+ expect(
+ within(card).queryByText(/This application uses React 18/),
+ ).not.toBeInTheDocument();
+
+ isLocalhostMock.mockRestore();
+ isHostAppInDevModeMock.mockRestore();
+ });
+
it("hides the problem when 'hide' is clicked", async () => {
setup({
authConfig: createMockSdkConfig(),
diff --git a/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.ts b/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.ts
index 740360ab53b..68bc8e3fb81 100644
--- a/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.ts
+++ b/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.ts
@@ -1,7 +1,12 @@
import { useEffect } from "react";
+import { getIsLocalhost } from "embedding-sdk-bundle/lib/get-is-localhost";
+import { getHostReactMajorVersion } from "embedding-sdk-bundle/lib/host-react-version";
+import { printUsageProblemToConsole } from "embedding-sdk-bundle/lib/print-usage-problem";
import { useMetabaseProviderPropsStore } from "embedding-sdk-bundle/lib/provider-props-store";
+import { toWarning } from "embedding-sdk-bundle/lib/usage-problem";
import { getBuildInfo } from "embedding-sdk-shared/lib/get-build-info";
+import { isHostAppInDevMode } from "embedding-sdk-shared/lib/is-host-app-in-dev-mode";
import {
isInvalidMetabaseVersion,
isSdkPackageCompatibleWithSdkBundle,
@@ -51,4 +56,13 @@ export const useLogVersionInfo = () => {
);
}
}, [allowConsoleLog, sdkPackageVersion, sdkBundleVersion]);
+
+ useEffect(() => {
+ // Development hosts already get this warning from the usage problem banner.
+ const isProductionHost = !getIsLocalhost() && !isHostAppInDevMode();
+
+ if (getHostReactMajorVersion() === 18 && isProductionHost) {
+ printUsageProblemToConsole(toWarning("REACT_18_DEPRECATED"));
+ }
+ }, []);
};
diff --git a/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.unit.spec.tsx b/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.unit.spec.tsx
index 2a230be0bfd..56ef5cd1a31 100644
--- a/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.unit.spec.tsx
+++ b/frontend/src/embedding-sdk-bundle/hooks/private/use-log-version-info/use-log-version-info.unit.spec.tsx
@@ -3,12 +3,28 @@ import "embedding-sdk-bundle";
import { EMBEDDING_SDK_BUNDLE_UNKNOWN_VERSION } from "build-configs/embedding-sdk/constants/versions";
import { useLogVersionInfo } from "embedding-sdk-bundle/hooks/private/use-log-version-info";
+import { getIsLocalhost } from "embedding-sdk-bundle/lib/get-is-localhost";
+import { getHostReactMajorVersion } from "embedding-sdk-bundle/lib/host-react-version";
+import { USAGE_PROBLEM_MESSAGES } from "embedding-sdk-bundle/lib/usage-problem";
import { getBuildInfo } from "embedding-sdk-shared/lib/get-build-info";
+import { isHostAppInDevMode } from "embedding-sdk-shared/lib/is-host-app-in-dev-mode";
jest.mock("embedding-sdk-shared/lib/get-build-info", () => ({
getBuildInfo: jest.fn(),
}));
+jest.mock("embedding-sdk-bundle/lib/get-is-localhost", () => ({
+ getIsLocalhost: jest.fn(),
+}));
+
+jest.mock("embedding-sdk-bundle/lib/host-react-version", () => ({
+ getHostReactMajorVersion: jest.fn(),
+}));
+
+jest.mock("embedding-sdk-shared/lib/is-host-app-in-dev-mode", () => ({
+ isHostAppInDevMode: jest.fn(),
+}));
+
const setup = async ({
sdkPackageVersion,
sdkBundleVersion,
@@ -84,4 +100,63 @@ describe("useLogVersionInfo", () => {
).toHaveLength(0);
});
});
+
+ describe("React 18 deprecation", () => {
+ const setupReactVersion = ({
+ hostReactMajorVersion,
+ isLocalhost = false,
+ isHostAppInDevelopmentMode = false,
+ }: {
+ hostReactMajorVersion: number;
+ isLocalhost?: boolean;
+ isHostAppInDevelopmentMode?: boolean;
+ }) => {
+ jest
+ .mocked(getHostReactMajorVersion)
+ .mockReturnValue(hostReactMajorVersion);
+ jest.mocked(getIsLocalhost).mockReturnValue(isLocalhost);
+ jest
+ .mocked(isHostAppInDevMode)
+ .mockReturnValue(isHostAppInDevelopmentMode);
+
+ renderHook(() => useLogVersionInfo());
+ };
+
+ const getReact18Warnings = () =>
+ getWarnMessages().filter((message) =>
+ message.includes(USAGE_PROBLEM_MESSAGES.REACT_18_DEPRECATED),
+ );
+
+ it("warns on a production host when the host app runs React 18", () => {
+ setupReactVersion({ hostReactMajorVersion: 18 });
+
+ const warnings = getReact18Warnings();
+
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain(
+ "https://www.metabase.com/docs/latest/embedding/sdk/introduction#modular-embedding-sdk-prerequisites",
+ );
+ });
+
+ it("leaves the warning to the usage problem on localhost", () => {
+ setupReactVersion({ hostReactMajorVersion: 18, isLocalhost: true });
+
+ expect(getReact18Warnings()).toHaveLength(0);
+ });
+
+ it("leaves the warning to the usage problem when the host app is in development mode", () => {
+ setupReactVersion({
+ hostReactMajorVersion: 18,
+ isHostAppInDevelopmentMode: true,
+ });
+
+ expect(getReact18Warnings()).toHaveLength(0);
+ });
+
+ it("does not warn when the host app runs React 19", () => {
+ setupReactVersion({ hostReactMajorVersion: 19 });
+
+ expect(getReact18Warnings()).toHaveLength(0);
+ });
+ });
});
diff --git a/frontend/src/embedding-sdk-bundle/hooks/private/use-sdk-usage-problem.ts b/frontend/src/embedding-sdk-bundle/hooks/private/use-sdk-usage-problem.ts
index f684dbf8a52..21ee424c664 100644
--- a/frontend/src/embedding-sdk-bundle/hooks/private/use-sdk-usage-problem.ts
+++ b/frontend/src/embedding-sdk-bundle/hooks/private/use-sdk-usage-problem.ts
@@ -6,6 +6,7 @@ import { useSdkDispatch, useSdkSelector } from "embedding-sdk-bundle/store";
import { setUsageProblem } from "embedding-sdk-bundle/store/reducer";
import {
getHasTokenFeature,
+ getInitStatus,
getIsGuestEmbedRaw,
getUsageProblem,
} from "embedding-sdk-bundle/store/selectors";
@@ -81,13 +82,25 @@ export function useSdkUsageProblem({
// are reflected here.
const usageProblem = useSdkSelector(getUsageProblem);
+ const initStatus = useSdkSelector(getInitStatus);
+
+ // Until init finishes, the problem can be wrongly inferred from the assumed
+ // settings values above, before the real ones load.
+ const isInitFinished =
+ initStatus.status === "success" || initStatus.status === "error";
+
useEffect(() => {
// Log the problem to the console once.
- if (!hasLoggedRef.current && allowConsoleLog) {
+ if (
+ !hasLoggedRef.current &&
+ allowConsoleLog &&
+ isInitFinished &&
+ usageProblem
+ ) {
printUsageProblemToConsole(usageProblem);
hasLoggedRef.current = true;
}
- }, [usageProblem, allowConsoleLog, dispatch]);
+ }, [usageProblem, allowConsoleLog, isInitFinished, dispatch]);
return usageProblem;
}
diff --git a/frontend/src/embedding-sdk-bundle/lib/host-react-version.ts b/frontend/src/embedding-sdk-bundle/lib/host-react-version.ts
new file mode 100644
index 00000000000..ccaf086da29
--- /dev/null
+++ b/frontend/src/embedding-sdk-bundle/lib/host-react-version.ts
@@ -0,0 +1,8 @@
+import { version as reactVersion } from "react";
+
+export function getHostReactMajorVersion(): number | null {
+ const majorVersion = parseInt(reactVersion, 10);
+
+ // Should be very rare: only when the host's `react` module has no usable `version`.
+ return Number.isNaN(majorVersion) ? null : majorVersion;
+}
diff --git a/frontend/src/embedding-sdk-bundle/lib/host-react-version.unit.spec.ts b/frontend/src/embedding-sdk-bundle/lib/host-react-version.unit.spec.ts
new file mode 100644
index 00000000000..d5d6eb5f3ef
--- /dev/null
+++ b/frontend/src/embedding-sdk-bundle/lib/host-react-version.unit.spec.ts
@@ -0,0 +1,28 @@
+import { getHostReactMajorVersion } from "./host-react-version";
+
+let mockReactVersion: string | undefined;
+
+jest.mock("react", () => ({
+ ...jest.requireActual("react"),
+ get version() {
+ return mockReactVersion;
+ },
+}));
+
+describe("getHostReactMajorVersion", () => {
+ it.each([
+ ["18.3.1", 18],
+ ["19.0.0", 19],
+ ["19.1.0-canary-abc", 19],
+ ])("returns the major of %s", (version, major) => {
+ mockReactVersion = version;
+
+ expect(getHostReactMajorVersion()).toBe(major);
+ });
+
+ it("returns null when the host React version is unknown", () => {
+ mockReactVersion = undefined;
+
+ expect(getHostReactMajorVersion()).toBeNull();
+ });
+});
diff --git a/frontend/src/embedding-sdk-bundle/lib/usage-problem.ts b/frontend/src/embedding-sdk-bundle/lib/usage-problem.ts
index 5915ba67a45..05dedcfe86e 100644
--- a/frontend/src/embedding-sdk-bundle/lib/usage-problem.ts
+++ b/frontend/src/embedding-sdk-bundle/lib/usage-problem.ts
@@ -5,6 +5,7 @@ import type {
SdkUsageProblem,
SdkUsageProblemKey,
} from "embedding-sdk-bundle/types/usage-problem";
+import { isHostAppInDevMode } from "embedding-sdk-shared/lib/is-host-app-in-dev-mode";
import {
EMBEDDING_SDK_CONFIG,
isEmbeddingEajs,
@@ -12,6 +13,7 @@ import {
import type { MetabaseEmbeddingSessionToken } from "metabase/embedding-sdk/types/refresh-token";
import { getIsLocalhost } from "./get-is-localhost";
+import { getHostReactMajorVersion } from "./host-react-version";
interface SdkProblemOptions {
authConfig: MetabaseAuthConfig;
@@ -41,6 +43,8 @@ export const USAGE_PROBLEM_MESSAGES = {
// eslint-disable-next-line metabase/no-literal-metabase-strings -- only shown in development.
DEVELOPMENT_MODE_CLOUD_INSTANCE: `This Metabase is in development mode intended exclusively for testing. Using this Metabase for everyday BI work or when embedding in production is considered unfair usage.`,
JWT_EXP_NULL: `The JWT token is missing the "exp" (expiration) claim. We will disallow tokens without "exp" in a future release. Please add "exp" to the token payload.`,
+ // eslint-disable-next-line metabase/no-literal-metabase-strings -- only shown to developers of the host app.
+ REACT_18_DEPRECATED: `This application uses React 18. The Metabase modular embedding SDK will require React 19 in a future release, and this embed will stop working once your Metabase instance is upgraded to it. Please upgrade your application to React 19.`,
} as const;
export const SDK_AUTH_DOCS_URL =
@@ -53,6 +57,10 @@ export const SDK_INTRODUCTION_DOCS_URL =
// eslint-disable-next-line metabase/no-unconditional-metabase-links-render -- these links are used in the SDK banner which is only shown to developers
"https://www.metabase.com/docs/latest/embedding/sdk/introduction#in-metabase";
+const SDK_PREREQUISITES_DOCS_URL =
+ // eslint-disable-next-line metabase/no-unconditional-metabase-links-render -- these links are used in the SDK banner which is only shown to developers
+ "https://www.metabase.com/docs/latest/embedding/sdk/introduction#modular-embedding-sdk-prerequisites";
+
/** Documentation for each kind of SDK usage problems */
export const USAGE_PROBLEM_DOC_URLS: Record<SdkUsageProblemKey, string> = {
API_KEYS_WITHOUT_LICENSE: METABASE_UPGRADE_URL,
@@ -61,6 +69,7 @@ export const USAGE_PROBLEM_DOC_URLS: Record<SdkUsageProblemKey, string> = {
EMBEDDING_SDK_NOT_ENABLED: SDK_INTRODUCTION_DOCS_URL,
DEVELOPMENT_MODE_CLOUD_INSTANCE: METABASE_UPGRADE_URL,
JWT_EXP_NULL: SDK_AUTH_DOCS_URL,
+ REACT_18_DEPRECATED: SDK_PREREQUISITES_DOCS_URL,
} as const;
/**
@@ -91,6 +100,8 @@ export function getSdkUsageProblem(
// in case of a local app running a distant MB instance
const isLocalhost = isLocalHost ?? getIsLocalhost();
+ const isDevelopmentHost = isLocalhost || isHostAppInDevMode();
+
if (isDevelopmentMode) {
return toWarning("DEVELOPMENT_MODE_CLOUD_INSTANCE");
}
@@ -116,6 +127,9 @@ export function getSdkUsageProblem(
isEnabled,
session,
isMcpApp,
+ isDevelopmentHost,
+ hostReactMajorVersion: getHostReactMajorVersion(),
+ isEajs: isEmbeddingEajs(),
})
// MCP Apps uses temporary sessions created by MCP backend.
.with({ isMcpApp: true }, () => null)
@@ -130,6 +144,16 @@ export function getSdkUsageProblem(
},
() => toError("EMBEDDING_SDK_NOT_ENABLED"),
)
+ // We do not allow using API keys in production.
+ .with({ isApiKey: true, hasTokenFeature: true, isLocalhost: false }, () =>
+ toError("API_KEYS_WITH_LICENSE"),
+ )
+ // The iframe embed renders with the React shipped by Metabase, so the
+ // host app's React version is not the customer's to upgrade there.
+ .with(
+ { hostReactMajorVersion: 18, isDevelopmentHost: true, isEajs: false },
+ () => toWarning("REACT_18_DEPRECATED"),
+ )
// For API keys, we allow evaluation usage without a license in localhost.
// This allows them to test-drive the SDK in development.
// API keys are always enabled regardless of the "enable-embedding" setting,
@@ -140,10 +164,6 @@ export function getSdkUsageProblem(
.with({ isLocalhost: true, isApiKey: true, hasTokenFeature: false }, () =>
toWarning("API_KEYS_WITHOUT_LICENSE"),
)
- // We do not allow using API keys in production.
- .with({ isApiKey: true, hasTokenFeature: true }, () =>
- toError("API_KEYS_WITH_LICENSE"),
- )
.with({ session: { exp: P.nullish } }, () => toWarning("JWT_EXP_NULL"))
.otherwise(() => null)
);
@@ -157,7 +177,7 @@ const toError = (type: SdkUsageProblemKey): SdkUsageProblem => ({
documentationUrl: USAGE_PROBLEM_DOC_URLS[type],
});
-const toWarning = (type: SdkUsageProblemKey): SdkUsageProblem => ({
+export const toWarning = (type: SdkUsageProblemKey): SdkUsageProblem => ({
type,
severity: "warning",
title: getTitle(),