A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Improve anywidget invalid module error messages (#10026)
Shahmir Varqha82a0ef6ad551
diff --git a/frontend/src/components/data-table/utils.ts b/frontend/src/components/data-table/utils.tsindex 96b92f9aaa..330902599d 100644--- a/frontend/src/components/data-table/utils.ts+++ b/frontend/src/components/data-table/utils.ts@@ -4,6 +4,7 @@ import type { Table } from "@tanstack/react-table";import type { TableData } from "@/plugins/impl/DataTablePlugin";import { vegaLoadData } from "@/plugins/impl/vega/loader";import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";+import { isRecord } from "@/utils/records";import { getMimeValues } from "./mime-cell";import type { DataType } from "@/core/kernel/messages";import {@@ -232,10 +233,6 @@ function stripHtml(html: string): string {const HTML_MIMETYPES = new Set(["text/html", "text/markdown"]);-function isRecord(value: unknown): value is Record<string, unknown> {- return value !== null && typeof value === "object" && !Array.isArray(value);-}-/*** Get clipboard-ready text and optional HTML for a cell.*diff --git a/frontend/src/core/islands/parse.ts b/frontend/src/core/islands/parse.tsindex 8e8e4d3c66..6662b70f66 100644--- a/frontend/src/core/islands/parse.ts+++ b/frontend/src/core/islands/parse.ts@@ -6,6 +6,7 @@ import {ISLANDS_JSON_SCRIPT_TYPE,} from "@/core/islands/constants";import { Logger } from "@/utils/Logger";+import { isRecord } from "@/utils/records";/*** DOM elements look like this:@@ -480,7 +481,3 @@ function isMarimoIslandPayloadCell(typeof cell.displayOutput === "boolean");}--function isRecord(value: unknown): value is Record<string, unknown> {- return typeof value === "object" && value !== null;-}diff --git a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsxindex 0e9080b531..6a023ae9ee 100644--- a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx+++ b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx@@ -10,6 +10,7 @@ import { createPlugin } from "@/plugins/core/builder";import type { IPluginProps } from "@/plugins/types";import { prettyError } from "@/utils/errors";import { Logger } from "@/utils/Logger";+import { hasFunctionProperty, isRecord } from "@/utils/records";import { ErrorBanner } from "../common/error-banner";import { getMarimoInternal, MODEL_MANAGER, type Model } from "./model";import type { ModelState, WidgetModelId } from "./types";@@ -140,10 +141,9 @@ const AnyWidgetSlot = (props: IPluginProps<ModelIdRef, Data>) => {}if (!isAnyWidgetModule(jsModule)) {- const error = new Error(- `Module at ${jsUrl} does not appear to be a valid anywidget`,+ return (+ <ErrorBanner error={getInvalidAnyWidgetModuleError(jsModule, jsUrl)} />);- return <ErrorBanner error={error} />;}return (@@ -200,6 +200,52 @@ function isAnyWidgetModule(mod: any): mod is { default: AnyWidget } {);}+function getInvalidAnyWidgetModuleError(mod: unknown, jsUrl: string): Error {+ const afmDocs = "https://anywidget.dev/en/afm/";+ const hasNamedRender = isRecord(mod) && hasFunctionProperty(mod, "render");+ const hasNamedInitialize =+ isRecord(mod) && hasFunctionProperty(mod, "initialize");++ if (hasNamedRender || hasNamedInitialize) {+ const namedExports = [+ hasNamedRender ? "`render`" : null,+ hasNamedInitialize ? "`initialize`" : null,+ ]+ .filter(Boolean)+ .join(" and ");+ const lifecycleHooks = [+ hasNamedRender ? "render" : null,+ hasNamedInitialize ? "initialize" : null,+ ].filter((hook): hook is string => hook !== null);+ const defaultExportExample = `export default { ${lifecycleHooks.join(", ")} }`;+ const namedExportExample =+ lifecycleHooks.length === 1+ ? `export function ${lifecycleHooks[0]}`+ : "named export function ...";+ return new Error(+ `Anywidget module at ${jsUrl} uses named exports (${namedExports}). ` ++ "Per the AFM spec, use a default export instead: " ++ `\`${defaultExportExample}\` (not \`${namedExportExample}\`). ` ++ `See ${afmDocs}`,+ );+ }++ if (!isRecord(mod) || mod.default === undefined) {+ return new Error(+ `Anywidget module at ${jsUrl} is missing a default export. ` ++ "Per the AFM spec, use `export default { render }` or " ++ "`export default async () => ({ render })`. " ++ `See ${afmDocs}`,+ );+ }++ return new Error(+ `Anywidget module at ${jsUrl} has an invalid default export. ` ++ "Expected a factory function or an object with `render` or `initialize`. " ++ `See ${afmDocs}`,+ );+}+interface Props<T extends AnyWidgetState> {widget: AnyWidget<T>;modelId: WidgetModelId;@@ -250,4 +296,5 @@ export const visibleForTesting = {LoadedSlot,runAnyWidgetModule,isAnyWidgetModule,+ getInvalidAnyWidgetModuleError,};diff --git a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsxindex a6e080cc56..94d3785ff3 100644--- a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx+++ b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx@@ -9,7 +9,8 @@ import { MODEL_MANAGER, Model } from "../model";import type { WidgetModelId } from "../types";import { BINDING_MANAGER } from "../widget-binding";-const { LoadedSlot } = visibleForTesting;+const { LoadedSlot, isAnyWidgetModule, getInvalidAnyWidgetModuleError } =+ visibleForTesting;// Helper to create typed model IDs for testsconst asModelId = (id: string): WidgetModelId => id as WidgetModelId;@@ -150,3 +151,71 @@ describe("LoadedSlot", () => {});});});++describe("isAnyWidgetModule", () => {+ it("should accept a default object with render", () => {+ expect(isAnyWidgetModule({ default: { render: () => undefined } })).toBe(+ true,+ );+ });++ it("should accept a default factory function", () => {+ expect(+ isAnyWidgetModule({ default: async () => ({ render: () => {} }) }),+ ).toBe(true);+ });++ it("should reject legacy named render exports", () => {+ expect(isAnyWidgetModule({ render: () => undefined })).toBe(false);+ });+});++describe("getInvalidAnyWidgetModuleError", () => {+ const jsUrl = "./@file/widget.js";++ it("should explain legacy named render exports", () => {+ const error = getInvalidAnyWidgetModuleError(+ { render: () => undefined },+ jsUrl,+ );+ expect(error.message).toContain("named exports (`render`)");+ expect(error.message).toContain("`export default { render }`");+ expect(error.message).toContain("not `export function render`");+ });++ it("should explain legacy named initialize exports", () => {+ const error = getInvalidAnyWidgetModuleError(+ { initialize: () => undefined },+ jsUrl,+ );+ expect(error.message).toContain("named exports (`initialize`)");+ expect(error.message).toContain("`export default { initialize }`");+ expect(error.message).toContain("not `export function initialize`");+ });++ it("should avoid nested backticks for multi-hook named exports", () => {+ const error = getInvalidAnyWidgetModuleError(+ { render: () => undefined, initialize: () => undefined },+ jsUrl,+ );+ expect(error.message).toContain(+ "`export default { render, initialize }` (not `named export function ...`).",+ );+ expect(error.message).not.toContain("`named `export");+ });++ it("should explain a missing default export", () => {+ expect(getInvalidAnyWidgetModuleError({}, jsUrl).message).toContain(+ "missing a default export",+ );+ expect(getInvalidAnyWidgetModuleError(null, jsUrl).message).toContain(+ "missing a default export",+ );+ });++ it("should explain an invalid default export", () => {+ const error = getInvalidAnyWidgetModuleError({ default: {} }, jsUrl);+ expect(error.message).toContain("invalid default export");+ expect(error.message).toContain("https://anywidget.dev/en/afm/");+ });+});diff --git a/frontend/src/utils/__tests__/records.test.ts b/frontend/src/utils/__tests__/records.test.tsnew file mode 100644index 0000000000..b624892f0a--- /dev/null+++ b/frontend/src/utils/__tests__/records.test.ts@@ -0,0 +1,27 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { describe, expect, it } from "vitest";+import { hasFunctionProperty, isRecord } from "../records";++describe("isRecord", () => {+ it("should accept plain objects", () => {+ expect(isRecord({})).toBe(true);+ expect(isRecord({ a: 1 })).toBe(true);+ });++ it("should reject null, arrays, and primitives", () => {+ expect(isRecord(null)).toBe(false);+ expect(isRecord([])).toBe(false);+ expect(isRecord("x")).toBe(false);+ expect(isRecord(1)).toBe(false);+ });+});++describe("hasFunctionProperty", () => {+ it("should detect function properties", () => {+ expect(hasFunctionProperty({ render: () => undefined }, "render")).toBe(+ true,+ );+ expect(hasFunctionProperty({ render: 1 }, "render")).toBe(false);+ });+});diff --git a/frontend/src/utils/records.ts b/frontend/src/utils/records.tsnew file mode 100644index 0000000000..73341b5060--- /dev/null+++ b/frontend/src/utils/records.ts@@ -0,0 +1,12 @@+/* Copyright 2026 Marimo. All rights reserved. */++export function isRecord(value: unknown): value is Record<string, unknown> {+ return value !== null && typeof value === "object" && !Array.isArray(value);+}++export function hasFunctionProperty(+ record: Record<string, unknown>,+ key: string,+): boolean {+ return typeof record[key] === "function";+}