Let executeJs expressions use values imported from JS modules

[totally-not-ai]

Why

A JavaScript expression sent from the server with executeJs is evaluated in the global scope, so it cannot use import to reach values exported by a JS module. The usual workaround is to hand-write a module whose only job is to republish those values on window.

This branch removes that workaround, and along the way finishes the runtime-ES-module support on @JavaScript that the same code paths touch.

Importing values for executeJs

@JsModule gains two optional attributes, imports and importAll. A class that sets either of them declares what to import rather than a side-effect module, and JsImports.of(TheClass.class) hands those values to an expression as an ordinary parameter:

@JsModule(value = "lit-html", imports = { "render", "html" })
final class LitImports {
}

element.executeJs("$0.render($0.html`<div>${$1}</div>`, this)",
        JsImports.of(LitImports.class), "Lit");

Because every reference is its own parameter, two modules exporting the same name never collide, so no renaming syntax is needed.

How it works:

• Each declaring class gets its own lazily loaded chunk, generated by AbstractUpdateImports, which publishes the values in a client-side registry (window.Vaadin.Flow.imports). The modules therefore stay out of the eager bundle.
• UIInternals requests that chunk as a dynamic import dependency whenever it sees a JsImports parameter (including ones captured by a JsFunction). The client loads a response's dependencies before running its JavaScript invocations, so the values are always registered by the time the expression is evaluated, and already requested chunks are dropped from the dependency list so repeated use loads the chunk once.
• JacksonCodec encodes the reference as @v-imports carrying the chunk id (not the Java class name), and ClientJsonCodec resolves it against the registry.
• The declarations are wired through both dependency scanners (FrontendClassVisitor/FrontendDependencies and FullDependenciesScanner), and a declared module is not also emitted as a side-effect import.
• BuildFrontendUtil counts modules reached only through @JsModule(imports = ...) when detecting commercial products.

Conflicting declarations fail the build rather than producing a broken chunk: the same name imported from two modules, importAll combined with other declarations on the class, imports and importAll on the same annotation, names that are not valid JavaScript identifiers, and imports declared from an external URL (such a module is not in the bundle, so the import could never be resolved).

Runtime ES modules via @JavaScript(type = MODULE)

@JavaScript gains a type attribute, and Page gains an addJavaScript(String, LoadMode, JavaScript.Type) overload that replaces the now-deprecated addJsModule(String) (the new overload also accepts a LoadMode). Type.MODULE renders a <script type="module">, is never bundled, and accepts bare relative URLs, which are normalized against the servlet context root with the same resolver the annotation path uses. LoadMode.INLINE is rejected for Type.MODULE, since the browser cannot be given a module's contents without losing the module's identity.

Fixes folded in

• developmentOnly is now honored for runtime JavaScript: @JavaScript(value = "devtools.js", type = MODULE, developmentOnly = true) was loaded in production. addExternalDependencies now skips development-only values in production mode, which also covers external @JavaScript and external @JsModule values where the flag was ignored even before type = MODULE existed.
• developmentOnly is now carried on JsImportsData and honored by the chunk generator, so such a declaration no longer pulls its module into the production bundle or counts as a used npm package.
• Resolving a declared module kept only the first path from getUniqueEs6ImportPaths, dropping the theme-translated and transitively imported files that a plain @JsModule emits. They are now emitted as side-effect imports in the same chunk, skipping paths already bound by name, so both spellings put the same files into the bundle.
• Page.addJavaScript(url, loadMode, MODULE) passed a bare relative URL through untouched, so the browser requested it relative to the current route and got a 404. It is now normalized, and a URL that cannot be normalized is rejected instead of silently broken.
• An external @JsModule declaring imports was still added to the page as a side-effect module script, running the module twice; it is now filtered out at runtime.

Testing

Unit tests for chunk generation and validation (AbstractUpdateImportsTest), both scanners, JsImports (including equality), JacksonCodec/DependencyList encoding, runtime dependency handling (RuntimeJavaScriptDependencyTest), ClientJsonCodec decoding of @v-imports and the unknown @v- guard, and commercial-product detection through JS module imports. Integration tests cover named imports, namespace imports, deferred use (JsImportsIT) and runtime type = MODULE scripts (RuntimeJavaScriptModuleIT).

Use case

An application has a component that draws a small sparkline chart. The markup is easiest to express as a Lit template, but the developer does not want to add a hand-written JS wrapper file to the project just so the server can call render and html — those are exports of lit-html, and a server-sent expression cannot import them.

Declaring the imports on a small class makes them available as an ordinary executeJs parameter:

@JsModule(value = "lit-html", imports = { "render", "html" })
final class LitImports {
}

@Route("dashboard")
public class SparklineCard extends Div {

    public void setValues(List<Integer> values) {
        String points = values.stream().map(String::valueOf)
                .collect(Collectors.joining(" "));
        getElement().executeJs("""
                $0.render(
                    $0.html`<svg viewBox="0 0 100 20"><polyline points=${$1}/></svg>`,
                    this)
                """, JsImports.of(LitImports.class), points);
    }
}

lit-html is loaded on demand in its own chunk the first time the expression is sent, so it does not weigh down the eager bundle of pages that never show the card.

API Changes

com.vaadin.flow.component.dependency.JavaScript

// Added
public enum Type // nested in the annotation; values SCRIPT, MODULE
Type type() default Type.SCRIPT // the kind of <script> tag to render

com.vaadin.flow.component.dependency.JsModule

// Added
String[] imports() default {} // names to import from the module and publish for the annotated class
boolean importAll() default false // import the whole module namespace instead of individual names

com.vaadin.flow.component.page.Page

// Added
public void addJavaScript(String url, LoadMode loadMode, JavaScript.Type type)

// Changed
- public void addJsModule(String url)
+ @Deprecated(since = "25.3") public void addJsModule(String url) // use addJavaScript(String, LoadMode, JavaScript.Type) with Type.MODULE

com.vaadin.flow.dom.JsImports

// Added
public final class JsImports implements Serializable
public static JsImports of(Class<?> declaringClass) // throws IllegalArgumentException if the class declares no JS module imports
public String getDeclaringClassName()
public String getChunkId() // internal use only
public boolean equals(Object obj)
public int hashCode()
public String toString()

com.vaadin.flow.server.frontend.scanner.JsImportsData

// Added
public class JsImportsData implements Serializable // internal use only
public JsImportsData(String className, String module, List<String> names, boolean importAll, boolean developmentOnly)
public String getClassName()
public String getModule()
public List<String> getNames()
public boolean isImportAll()
public boolean isDevelopmentOnly()
public boolean equals(Object obj)
public int hashCode()
public String toString()

com.vaadin.flow.server.frontend.scanner.FrontendDependenciesScanner

// Added
default List<JsImportsData> getJsImports() // returns List.of() by default, so implementations need no change

com.vaadin.flow.server.frontend.scanner.FrontendDependencies

// Added
public List<JsImportsData> getJsImports() // sorted by class name for stable chunk generation

[github-actions]

Test Results

 1 377 files  + 5   1 378 suites  +5   1h 28m 40s ⏱️ + 1m 31s
10 524 tests +80  10 457 ✅ +80  67 💤 ±0  0 ❌ ±0 
10 843 runs  +80  10 775 ✅ +80  68 💤 ±0  0 ❌ ±0 

Results for commit 9eb5cb1. ± Comparison against base commit e107185.

♻️ This comment has been updated with latest results.

[sonarqubecloud]

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud