feat: serve @JavaScript with a runtime prefix as a runtime <script>

[Artur-]

@javascript values with a runtime prefix (context://, base://, /abs, http(s)://, //) are now served as runtime <script> elements rather than bundled, matching how the corresponding @Stylesheet values are resolved.

• New FrontendDependencyUrlResolver.isRuntimeDependencyUrl recognises the runtime prefix table (http(s)://, //, context://, base://, /abs) and is the single source of truth for distinguishing runtime URLs from bundler import specifiers.
• UIInternals treats such @javascript values as runtime dependencies via isRuntimeJavaScript, alongside type=MODULE values.
• Both dependency scanners (FrontendClassVisitor for production and FullDependenciesScanner for dev mode) filter runtime-prefixed @JavaScript values out of the bundle imports.
• Bare-relative @JavaScript values are still bundled for backwards compatibility, but FrontendDependencies logs a single build-time warning that lists every such usage. The warning recommends @JsModule for bundling, or moving the file to a static location and using a runtime prefix. The @JavaScript javadoc documents this interpretation as deprecated.

Behavior change: before this change, @JavaScript("/foo.js") pointing at frontend/foo.js was bundled, because the bundler resolves a leading slash against the frontend folder. It now renders <script src="/foo.js"> resolved against the context root, which returns 404 unless the file is also served as a static resource. No build-time warning covers this form, since a leading slash is now a valid runtime URL and the scanner cannot tell the two uses apart. To keep bundling such a file, switch to @JsModule("./foo.js"). This needs a release note.

Production-mode fix: developmentOnly = true is now honoured for dependencies that are loaded at runtime instead of bundled. Before, a runtime @JavaScript value (runtime prefix or Type.MODULE) or an external @JsModule URL such as @JsModule(value = "https://…/dev-helper.js", developmentOnly = true) was also loaded in production. The @JsModule case and the prefixed @JavaScript cases other than a leading / were already affected before this PR.

Hotswap: a runtime @JavaScript value is added as a <script> element, which cannot be removed from the page. When such a value is changed or removed on a component in use, the new JavaScriptHotswapper reloads the affected UIs instead of refreshing them, so the old script is not left running next to the new one. Adding a value still only refreshes. To share the runtime check, FrontendDependencyUrlResolver.isRuntimeJavaScript(JavaScript) is added and ComponentMetaData.DependencyInfo.getJavaScripts() is made public (both internal-use classes).

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[github-actions]

Test Results

 1 668 files  + 1   1 754 suites  +1   2h 12m 25s ⏱️ + 4m 10s
12 968 tests +28  12 899 ✅ +28  69 💤 ±0  0 ❌ ±0 
13 602 runs  +28  13 533 ✅ +28  69 💤 ±0  0 ❌ ±0 

Results for commit 894880d. ± Comparison against base commit a59da97.

♻️ This comment has been updated with latest results.

[Artur-]

Merge main.

[github-actions]

Memory footprint

No change compared with the base commit a59da97.

[totally-not-ai]

Fixed the java:S1449 issue: URL prefix checks now lower-case with Locale.ROOT, so they don't depend on the default locale (e.g. the Turkish dotless i). resolveToContextRoot now reuses isRuntimeDependencyUrl instead of its own copy of the same prefix check, which had the same locale problem.

[Artur-]

merge main

[totally-not-ai]

@Artur- Merged latest main into the branch (no conflicts); flow-server compiles and the resolver tests pass.

[github-actions]

Runtime-prefixed @JavaScript values now take the same path out of the bundle as @StyleSheet values

flowchart LR
    subgraph Before
        direction TB
        B1["JavaScript annotation ((foo.js/redacted) -->|"build-time scan"| B2["FrontendClassVisitor.JSAnnotationVisitor: not type=MODULE, so bundle it"]
        B1 -->|"render time"| B3["UIInternals.isRuntimeJavaScript(): not MODULE, not UrlUtil.isExternal() - not runtime"]
        B2 --> B4["classInfo.scripts (bundle import)"]
        B3 --> B5["no runtime script tag emitted"]
    end
    subgraph After
        direction TB
        A1["JavaScript annotation ((foo.js/redacted) -->|"build-time scan"| A2["FrontendDependencyUrlResolver.isRuntimeDependencyUrl() true - skip bundle"]:::changed
        A1 -->|"render time"| A3["FrontendDependencyUrlResolver.isRuntimeDependencyUrl() true - is runtime"]:::changed
        A2 --> A4["excluded from classInfo.scripts"]
        A3 --> A5["UIInternals.addRuntimeDependencies() emits script tag"]:::changed
    end
    Before ~~~ After
    classDef changed stroke:#c9a227,stroke-width:3px

Loading

Before this PR, the build-time scanner (FrontendClassVisitor.JSAnnotationVisitor) only excluded type=MODULE values from the bundle, so a runtime-prefixed value like (foo.js/redacted) still went into classInfo.scripts, while UIInternals.isRuntimeJavaScript()only recognizedtype=MODULEorUrlUtil.isExternal()(plainhttp(s)://///) as runtime, so no (script)tag was ever emitted for it. The newFrontendDependencyUrlResolver.isRuntimeDependencyUrl()` predicate is now the single check both sides use, so the same value is consistently excluded from the bundle and served as a runtime script.

Diagram Bot draws the mechanism this pull request touches; it does not review the change. Verify it against the diff.

Generated by Diagram Bot for #24653 · agent · 82.8 AIC · ⊞ 9.2K · ◷

[vaadin-review-bot]

Reviewed the changes — left 1 comment and collected 2 findings below that could not be attached to the diff.

	Finding
⚠️	Only the bytecode scanner excludes runtime-prefixed @javascript values; the full scanner, which is the default in dev mode, still bundles them
📝	The @javascript javadoc still documents bundled bare-relative values as normal behavior while the build now calls that usage deprecated
📝	The deprecation warning's first two suggestions do not work for files in the frontend directory

⚠️ Only the bytecode scanner excludes runtime-prefixed @javascript values; the full scanner, which is the default in dev mode, still bundles them
FullDependenciesScanner.collectScripts got the Type.MODULE exclusion but not the new runtime-prefix exclusion. It is the scanner selected whenever optimizeBundle is false, which is the default for dev mode (DevModeInitializer) and for BuildFrontendUtil's dev-bundle path.

context:// and base:// survive this because AbstractUpdateImports.resolveModules filters those prefixes later, but a leading-slash value does not: @JavaScript("/absolute.js") still ends up as import '/absolute.js'; in the generated imports while also being added as a runtime <script>. So the feature behaves one way in a production build and another way in dev.

The module-exclusion equivalent has a test in both scanners (FullDependenciesScannerTest.getScripts_javaScriptWithTypeModule_excludedFromBundleImports); the runtime-prefix exclusion only has one in FrontendDependenciesTest.
_{FullDependenciesScanner.java:395 · correctness}

📝 The @javascript javadoc still documents bundled bare-relative values as normal behavior while the build now calls that usage deprecated
Two mismatches introduced by this change:

• The class javadoc says "Other paths used in the value() method are considered as relative to frontend directory and they are bundled". Leading-slash and base:// values are no longer bundled.
• Nothing in the annotation says the bundled interpretation is deprecated, and neither @JavaScript nor value() carries @Deprecated, yet every build now prints "uses the deprecated bundled interpretation" for the usage the javadoc presents as the normal one.
  _{JavaScript.java:55 · documentation}

[vaadin-review-bot]

📝 The deprecation warning's first two suggestions do not work for files in the frontend directory

Bare-relative @JavaScript values are documented as relative to the frontend directory. Both context:// and Type.MODULE resolve against the servlet context root, where such a file is not served, so following either suggestion gives a 404 unless the file is also moved out of frontend/. Only the @JsModule suggestion works as written.

The warning also fires for classes from third-party add-ons, which the application developer cannot change and cannot silence.

_{FrontendDependencies.java:247 · documentation}

[totally-not-ai]

@vaadin-review-bot Good catch. I reworded the warning. Its first suggestion now says to replace @JavaScript with @JsModule using the same value, which works as-is for files in frontend/. For loading at runtime, it now says the file must first be moved out of frontend/ to a statically served location (e.g. src/main/resources/META-INF/resources), and only then be referenced with context:// or type = Type.MODULE. Since add-on annotations can't be changed by the app developer, the warning is now logged once per scan with all usages listed, instead of once per annotation. It also notes that usages in add-ons need to be updated by the add-on maintainer.

[totally-not-ai]

@vaadin-review-bot Addressed the two findings that weren't attached to the diff:

• Full scanner: FullDependenciesScanner.collectScripts now skips runtime-prefixed @JavaScript values in the same way as the bytecode scanner. This means @JavaScript("/absolute.js") is no longer emitted as an import in dev mode. The FullDependenciesScannerTest sample component now includes context://, base:// and leading-slash values, and the test checks that only the bare relative value is bundled.
• Javadoc: the class and value() javadoc now list the runtime prefixes, including leading / and base://, and state that these are never bundled. They also say that the bundled interpretation of bare relative values is deprecated and point to @JsModule instead. I didn't add @Deprecated to value() because only one interpretation of its values is deprecated, not the attribute itself.

[totally-not-ai]

Replaced the lambda with JavaScript::value in UIInternals (S1612). I left the S1066 finding at UIInternals.java:2231 (setChildModeless) as it is: that nested if is existing code this PR doesn't touch, so changing it here would add unrelated changes to the diff.

[mcollovati]

It looks like there's an issue with hotswap: if I change the value for a @Javascript annotation that now is served as <script>, the browser will load the new JavaScript and also keep the old one.
IIRC, a loaded JavaScript cannot be removed from the page, but I wonder if the hotswapper should reload the page instead of doing a refresh in this case.

[totally-not-ai]

@mcollovati Good catch. A script that has run cannot be removed from the page, so a refresh can only add the new <script> next to the old one. I added a JavaScriptHotswapper. Before the metadata cache is cleared, it records the runtime @JavaScript values (value and type) of each redefined component. If any of them was removed or changed, it requests UIUpdateStrategy.RELOAD for every UI where the component is in use. Only adding a value keeps the refresh, because the new script is simply added. Bundled @JavaScript values are not affected. To share the runtime check with UIInternals, it moved to FrontendDependencyUrlResolver.isRuntimeJavaScript. JavaScriptHotswapperTest covers changing the value, changing the type, adding a value, a bundled value, and a component that is not in use.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud