feat: modules can be imported from a url

define_module(name, url="/static/bundle.mjs") imports the module from
the url instead of shipping the code over the widget model (e.g. a
bundle served from the app's static dir, cacheable and preloadable).
Exactly one of module (a Path), code= or url= must be passed; a plain
str still works as module code for backwards compatibility, with a
DeprecationWarning.

Note: under solara server define_module is patched by solara.server.esm,
which needs the matching update (widgetti/solara#1169) for the new
signature to apply there.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: maartenbreddels

ipyreact/module.py

@@ -1,5 +1,6 @@
+import warnings
 from pathlib import Path
-from typing import List, Union
+from typing import List, Optional, Union
 
 import traitlets
 from ipywidgets import DOMWidget
@@ -18,7 +19,10 @@ class Module(DOMWidget):
     _view_module = Unicode(module_name).tag(sync=True)
     _view_module_version = Unicode(module_version).tag(sync=True)
     name = Unicode(allow_none=False).tag(sync=True)
-    code = Unicode(allow_none=False).tag(sync=True)
+    code = Unicode("").tag(sync=True)
+    # when set, the module is imported from this url instead of shipping the
+    # code over the widget model (e.g. a bundle served from a static dir)
+    url = Unicode(None, allow_none=True).tag(sync=True)
     dependencies = traitlets.List(Unicode(), allow_none=True).tag(sync=True)
     status = Unicode(allow_none=True).tag(sync=True)
     react_version = Int(18).tag(sync=True)
@@ -32,15 +36,36 @@ def get_module_names():
     return _standard_dependencies
 
 
-def define_module(name, module: Union[str, Path]):
+def define_module(name, module: Union[str, Path, None] = None, *, code: Optional[str] = None, url: Optional[str] = None):
     """Register a ES module under a name.
 
     Parameters
     ----------
     name: str
         Name of the es module to register
-    module: str | Path
-        The module code to register
+    module: Path
+        Path to the module source on disk
+    code: str
+        The module source as a string
+    url: str
+        A url the module is served from (e.g. a bundle in the app's
+        static dir)
     """
+    if sum(x is not None for x in (module, code, url)) != 1:
+        raise TypeError("pass exactly one of module (a Path), code or url")
+    if isinstance(module, str):
+        # the pre-0.6 API: a plain str was module code
+        warnings.warn(
+            "passing module code as a plain str is deprecated, use code=... (or url=... for a url)",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        code = module
+        module = None
     _standard_dependencies.append(name)
-    return Module(code=module if not isinstance(module, Path) else module.read_text(encoding="utf8"), name=name)
+    if url is not None:
+        return Module(url=url, name=name)
+    if code is None:
+        assert module is not None
+        code = module.read_text(encoding="utf8")
+    return Module(code=code, name=name)

src/widget.tsx

@@ -310,13 +310,14 @@ export class Module extends WidgetModel {
       _view_name: Module.view_name,
       _view_module: Module.view_module,
       _view_module_version: Module.view_module_version,
+      url: null,
     };
   }
   initialize(attributes: any, options: any): void {
     super.initialize(attributes, options);
     this.addModule();
     // hot reload: re-import when the kernel ships new module code
-    this.on("change:code change:dependencies", () => {
+    this.on("change:code change:url change:dependencies", () => {
       invalidateModule(this.get("name"));
       this.addModule();
     });
@@ -342,12 +343,13 @@ export class Module extends WidgetModel {
     const code = this.get("code");
     let name = this.get("name");
     try {
-      if (this.codeUrl) {
+      if (this.codeUrl && this.codeUrl.startsWith("blob:")) {
         URL.revokeObjectURL(this.codeUrl);
       }
-      this.codeUrl = URL.createObjectURL(
-        new Blob([code], { type: "text/javascript" }),
-      );
+      const moduleUrl: string | null = this.get("url");
+      this.codeUrl = moduleUrl
+        ? moduleUrl
+        : URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
       let dependencies = this.get("dependencies") || [];
       this.set(
         "status",
@@ -357,7 +359,7 @@ export class Module extends WidgetModel {
       await ensureImportShimLoaded();
       await this.updateImportMap();
       this.set("status", "Loading module...");
-      let module = await importShim(this.codeUrl);
+      let module = await importShim(this.codeUrl!);
       try {
         // remapping an already-resolved specifier throws (hot reload in the
         // same page); the module registry is the source of truth, so only
@@ -888,7 +890,7 @@ export class ReactModel extends DOMWidgetModel {
   private rejectComponent: (value: any) => void;
   private compiledCode: string | null = null;
   private compileError: any | null = null;
-  private codeUrl: string | null = null;
+  private codeUrl: string | null;
   // this used so that the WrapperComponent can be rendered synchronously,
   private currentComponentToWrapOrError: any = null;
   private queue: Promise<any>;

tests/unit/define_module_test.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+
+import pytest
+
+import ipyreact
+
+
+def test_define_module_url():
+    module = ipyreact.define_module("t-url", url="/static/bundle.mjs")
+    assert module.url == "/static/bundle.mjs"
+    assert module.code == ""
+
+
+def test_define_module_code():
+    module = ipyreact.define_module("t-code", code="export default 1")
+    assert module.code == "export default 1"
+    assert module.url is None
+
+
+def test_define_module_path(tmp_path: Path):
+    file = tmp_path / "bundle.mjs"
+    file.write_text("export default 2")
+    module = ipyreact.define_module("t-path", file)
+    assert module.code == "export default 2"
+
+
+def test_define_module_str_is_deprecated_code():
+    with pytest.warns(DeprecationWarning, match="code="):
+        module = ipyreact.define_module("t-str", "export default 3")
+    assert module.code == "export default 3"
+
+
+def test_define_module_exactly_one():
+    with pytest.raises(TypeError, match="exactly one"):
+        ipyreact.define_module("t-none")
+    with pytest.raises(TypeError, match="exactly one"):
+        ipyreact.define_module("t-both", Path("x"), code="y")