fix: require is not defined in widgets

Author: righ

packages/docs/astro.config.mjs

@@ -134,5 +134,16 @@ export default defineConfig({
     define: {
       __webpack_public_path__: '""',
     },
+    build: {
+      commonjsOptions: {
+        // @jupyter-widgets/* (and some of their @jupyterlab transitives) ship
+        // ESM modules that still call `require()` at runtime — Rollup leaves
+        // those untouched by default, which surfaces in production as
+        // `ReferenceError: require is not defined`. transformMixedEsModules
+        // lets the CommonJS plugin rewrite those `require` calls into static
+        // imports at build time.
+        transformMixedEsModules: true,
+      },
+    },
   },
 });

packages/docs/src/content/docs/install-wizard.mdx

@@ -232,14 +232,19 @@ import { createWidgetsPlugin } from '@jupyter-kit/widgets';
 import { createPyodideExecutor } from '@jupyter-kit/executor-pyodide';
 
 <Notebook
-  executor={createPyodideExecutor()}
+  // Preloading `ipywidgets` is required for live mode — `autoloadImports`
+  // doesn't reliably see `from ipywidgets import ...`, and the comm shim
+  // must be wired before any cell runs. See the widgets reference for why.
+  executor={createPyodideExecutor({ packages: ['ipywidgets'] })}
   plugins={[createWidgetsPlugin()]}
   ...
 />
 ```
 
 See the [widgets gallery demo](/demos/pyodide/) (select _widgets-gallery_
-in the fixture dropdown).
+in the fixture dropdown) and the
+[widgets reference](/reference/widgets/#live-pyodide) for the preload
+gotcha.
 
 ## Upgrading CodeMirror, React, etc.
 

packages/docs/src/content/docs/reference/widgets.mdx

@@ -44,6 +44,65 @@ import { createWidgetsPlugin } from '@jupyter-kit/widgets';
 
 The executor's `commProvider` is auto-detected — no extra wiring.
 
+:::caution[Preload `ipywidgets`]
+`packages: ['ipywidgets']` is required, not just decorative. Pyodide's
+`autoloadImports` scanner walks the cell source for top-level `import X`
+statements but **misses `from ipywidgets import ...`** in many widget
+notebooks (and even when it sees them, the comm shim must already be
+wired before the first `.observe()` call). Preloading guarantees the
+package is ready and the JS-side comm handler is hooked up before any
+cell runs.
+:::
+
+## Bundler config (Vite, Rollup, webpack)
+
+`@jupyter-widgets/*` ship as ESM that still calls `require()` at runtime
+in a few spots — a webpack-era hybrid pattern. This is **upstream
+behaviour, not something `@jupyter-kit` can normalize from this side** —
+the `require()` calls live inside the published `@jupyter-widgets` builds.
+Modern bundlers don't inject a CJS shim for ESM by default, so without
+the right config you'll see one of these in the browser console:
+
+```
+Uncaught ReferenceError: require is not defined
+Uncaught ReferenceError: __webpack_public_path__ is not defined
+```
+
+### Vite (and Astro)
+
+```ts
+// vite.config.ts (or `vite:` block in astro.config)
+export default defineConfig({
+  build: {
+    commonjsOptions: {
+      // Rewrites `require()` calls inside ESM-flagged files into static
+      // imports at build time. Required for @jupyter-widgets/*.
+      transformMixedEsModules: true,
+    },
+  },
+  define: {
+    // The widget bundle references `__webpack_public_path__` for chunk
+    // URLs. Vite has no such global; replace with an empty string.
+    __webpack_public_path__: '""',
+  },
+});
+```
+
+`@jupyter-kit/widgets@3.0.0-rc.5+` already sets
+`globalThis.__webpack_public_path__ = ''` at module init as a runtime
+shim, so the `define` is belt-and-suspenders for older versions or
+unusual bundle splits.
+
+### webpack
+
+webpack handles both natively — no extra config required. Just install
+`@jupyter-kit/widgets` and use the `<Notebook>` component.
+
+### Rollup (without Vite)
+
+`@rollup/plugin-commonjs` with `transformMixedEsModules: true`. Pair with
+`@rollup/plugin-replace` for `__webpack_public_path__: '""'`.
+
 ## Bundle cost
 
 The plugin pulls in `@jupyter-widgets/{base,base-manager,controls,html-manager,output}`

packages/storybook/.examples/with-pyodide.stories.tsx

@@ -4,17 +4,26 @@ import { Notebook } from '@jupyter-kit/react';
 import { python as pythonHighlight } from '@jupyter-kit/core/langs/python';
 import { createEditorPlugin } from '@jupyter-kit/editor-codemirror';
 import { createKatexPlugin } from '@jupyter-kit/katex';
+import { createWidgetsPlugin } from '@jupyter-kit/widgets';
 import {
   createPyodideExecutor,
   type PyodideStatus,
 } from '@jupyter-kit/executor-pyodide';
 import { python as pythonEditor } from '@codemirror/lang-python';
 
 import showcase from '@jupyter-kit/fixtures/ipynb/showcase';
+import lorenz from '@jupyter-kit/fixtures/ipynb/Lorenz';
+import widgetsGallery from '@jupyter-kit/fixtures/ipynb/widgets-gallery';
 import '@jupyter-kit/theme-default/default.css';
 import '@jupyter-kit/theme-default/syntax/one-dark.css';
 import 'katex/dist/katex.min.css';
 
+const FIXTURES: Record<string, unknown> = {
+  showcase,
+  Lorenz: lorenz,
+  'widgets-gallery': widgetsGallery,
+};
+
 const meta: Meta = {
   title: 'Executor / Pyodide',
   component: Notebook,
@@ -24,10 +33,16 @@ export default meta;
 const Template = (preinstall: string[] = []) =>
   function Story() {
     const [status, setStatus] = useState<PyodideStatus>('idle');
+    const [fixture, setFixture] = useState<string>('showcase');
     const executor = useMemo(
       () =>
         createPyodideExecutor({
-          packages: preinstall,
+          // `ipywidgets` is a pyodide-bundled package but `loadPackagesFromImports`
+          // only sees it when `import ipywidgets` appears literally in the cell
+          // source (the widgets-gallery fixture writes `from ipywidgets import ...`,
+          // and the scanner catches that — but we preload anyway so the comm shim
+          // is wired up before any cell runs).
+          packages: ['ipywidgets', ...preinstall],
           autoloadImports: true,
           onStatus: setStatus,
         }),
@@ -36,6 +51,7 @@ const Template = (preinstall: string[] = []) =>
     const plugins = useMemo(
       () => [
         createKatexPlugin(),
+        createWidgetsPlugin(),
         createEditorPlugin({ languages: { python: pythonEditor() } }),
       ],
       [],
@@ -44,16 +60,32 @@ const Template = (preinstall: string[] = []) =>
       <div>
         <div
           style={{
+            display: 'flex',
+            gap: 12,
+            alignItems: 'center',
             padding: '8px 12px',
             fontFamily: 'monospace',
             fontSize: 12,
-            opacity: 0.7,
           }}
         >
-          pyodide: {status}
+          <label>
+            fixture:{' '}
+            <select
+              value={fixture}
+              onChange={(e) => setFixture(e.target.value)}
+              style={{ fontFamily: 'inherit', fontSize: 12 }}
+            >
+              {Object.keys(FIXTURES).map((k) => (
+                <option key={k} value={k}>
+                  {k}
+                </option>
+              ))}
+            </select>
+          </label>
+          <span style={{ opacity: 0.7 }}>pyodide: {status}</span>
         </div>
         <Notebook
-          ipynb={showcase as never}
+          ipynb={FIXTURES[fixture] as never}
           language="python"
           languages={[pythonHighlight]}
           plugins={plugins}

packages/storybook/package.json

@@ -26,6 +26,7 @@
     "@jupyter-kit/mathjax-cdn": "workspace:*",
     "@jupyter-kit/react": "workspace:*",
     "@jupyter-kit/theme": "workspace:*",
+    "@jupyter-kit/widgets": "workspace:*",
     "katex": "^0.16.9",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"