fix: clarify @JsModule, @CssImport, @JavaScript, @StyleSheet semantics#24207
Draft
Artur- wants to merge 5 commits into
Draft
fix: clarify @JsModule, @CssImport, @JavaScript, @StyleSheet semantics#24207Artur- wants to merge 5 commits into
Artur- wants to merge 5 commits into
Conversation
Artur-
force-pushed
the
feature/clarify-javascript-jsmodule-stylesheet
branch
2 times, most recently
from
365f4b2 to
84ca840
Compare
|
github-project-automation
Bot
moved this to 🔎Iteration reviews
in Vaadin Flow | Hilla | Kits ongoing work
mshabarov
moved this from 🔎Iteration reviews
to ⚒️ In progress
in Vaadin Flow | Hilla | Kits ongoing work
Artur-
changed the title
mshabarov
moved this from ⚒️ In progress
to 🪵Product backlog
in Vaadin Flow | Hilla | Kits ongoing work
Artur-
force-pushed
the
feature/clarify-javascript-jsmodule-stylesheet
branch
2 times, most recently
from
62a3691 to
83166a7
Compare
Lets a @javascript annotation render as a <script type="module"> tag instead of a classic <script>, so hand-authored or CDN-hosted ES modules can be loaded at runtime through annotations without going through Vite. For build-time bundled ES modules @jsmodule remains the right tool. The new @JavaScript.Type enum has values SCRIPT (default, current behavior) and MODULE. The annotation gains a type() attribute that selects between them. To make @javascript the unified entry point on the programmatic side as well, this commit also: - adds a new Page.addJavaScript(String url, LoadMode loadMode, JavaScript.Type type) overload that handles both classic <script> and <script type="module"> tags, with full LoadMode support for both; - delegates the existing addJavaScript(String, LoadMode) and addJavaScript(String) overloads to the new method with Type.SCRIPT; - deprecates Page.addJsModule(String) — recommend addJavaScript(url, loadMode, Type.MODULE) instead. The deprecated method keeps working for backwards compatibility. UIInternals.addExternalDependencies routes both @javascript runtime values and external @jsmodule values through the new addJavaScript overload. @javascript values pass js.loadMode() and js.type() straight through, so type=MODULE supports LAZY and INLINE load modes just like type=SCRIPT. FrontendClassVisitor.JSAnnotationVisitor reads the type enum via a new visitEnum override and skips MODULE-typed values from the bundle imports collection. The type attribute does not exist on @jsmodule, so visitEnum is a no-op for it. Existing @javascript usages keep their behavior: bare relative values default to type=SCRIPT and continue to bundle (legacy interpretation), external URLs continue to render as runtime <script> tags.
@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. - The scanner (FrontendClassVisitor) filters runtime-prefixed @javascript values out of the bundle imports. - Bare-relative @javascript values still bundle for backwards compatibility but FrontendDependencies emits a one-time consolidated build-time warning per (class, value) recommending migration.
@jsmodule is for build-time bundle sources only. A @jsmodule value with a runtime URL prefix (context://, base://, /abs, http(s)://, //) keeps working at runtime via Page.addJsModule, but is now filtered out of the bundle imports and triggers a build-time deprecation warning. - The scanner (FrontendClassVisitor) tracks such values on ClassInfo.deprecatedRuntimeModules instead of adding them to the bundle imports. - FrontendDependencies emits a one-time consolidated build-time warning per (class, value) recommending migration to @javascript(value=..., type=Type.MODULE) for runtime <script type="module"> loading. This removes the previous double-load where an external @jsmodule URL was both bundled and loaded at runtime.
…layout TaskCopyFrontendFiles still scans META-INF/resources/frontend/ for backwards compatibility, but that location is deprecated. Emit a once-per-jar/dir warning recommending the split layout: bundle sources for @JsModule/@CssImport under META-INF/frontend/, and runtime resources for @StyleSheet/@javascript under META-INF/resources/ (served directly by the servlet container).
Rewrites the Javadoc for all four dependency annotations to describe the bundle-source vs runtime distinction, the source locations, and the URL prefix table. Page.addStyleSheet/addJavaScript Javadoc cross-references the annotation prefix tables. Establishes a clean four-quadrant model: - @jsmodule / @CssImport: build-time bundle sources, fed into Vite. App source: src/main/frontend/. Addon source: META-INF/frontend/ (with META-INF/resources/frontend/ kept for compatibility but deprecated). - @Stylesheet / @javascript: runtime <link>/<script> elements served by the servlet container from META-INF/resources/. Relative URLs always resolve against the context root, regardless of servlet mapping. References #22888, #23326, #16780 and the v25 web-component-path / CSS-loading forum threads.
Artur-
force-pushed
the
feature/clarify-javascript-jsmodule-stylesheet
branch
from
83166a7 to
83b5a00
Compare
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Establishes a clean model:
@JsModule/@CssImport: build-time bundle sources, fed into Vite. App source:src/main/frontend/. Addon source:META-INF/frontend/(withMETA-INF/resources/frontend/kept for compatibility but deprecated).@StyleSheet/@JavaScript: runtime<link>/<script>elements served by the servlet container fromMETA-INF/resources/. Relative URLs always resolve against the context root, regardless of servlet mapping.@JavaScripthas atypeattribute (Type.SCRIPTdefault, orType.MODULEfor<script type="module">), so CDN-hosted and hand-authored ES modules can be loaded at runtime through annotations as well.Incompatible user-facing changes
@StyleSheet("foo.css")on a Component, app on custom servlet mapping (e.g./app/*): now resolves to<contextroot>/foo.cssinstead of 404'ing under/app/foo.css. Bug fix; nothing to do. If you actually wanted servlet-mapping-relative loading, write@StyleSheet("base://foo.css").Compatible changes
@StyleSheet("../foo.css")(any..path): now logs a WARN and is silently dropped at component level too (AppShell already did this). Remove the traversal — put the file at a non-traversing path underMETA-INF/resources/and reference it directly.@StyleSheetfile ("foo.css"+"./foo.css"+"context://foo.css"): now deduplicated to one<link>tag.@JavaScript("./foo.js")or@JavaScript("foo.js")(bare relative, defaulttype=Type.SCRIPT): build-time WARN "uses the deprecated bundled interpretation. Prependcontext://for a runtime<script>tag, settype=Type.MODULEfor a runtime<script type="module">tag, or migrate to@JsModulefor bundling." Still bundles for now. Pick one:@JsModule("./foo.js")if you wanted Vite to bundle it (file stays insrc/main/frontend/or addonMETA-INF/frontend/);@JavaScript("context://foo.js")for a plain runtime<script>(move file tosrc/main/resources/META-INF/resources/foo.jsor addonMETA-INF/resources/foo.js);@JavaScript(value="foo.js", type=Type.MODULE)for a runtime<script type="module">(same file location as the previous option).@JsModule("https://cdn.example.com/foo.js")(or anyhttp://,https://,//,context://,base://,/abs): build-time WARN "is a runtime URL.@JsModuleis for build-time bundle sources only; use@JavaScript(value="...", type=Type.MODULE)for a runtime<script type="module">tag." Still loaded at runtime as<script type="module">(no longer also bundled). Switch to@JavaScript(value="https://cdn.example.com/foo.js", type=Type.MODULE)to preserve the module semantics, or to plain@JavaScript("https://cdn.example.com/foo.js")if you actually wanted a classic<script>tag.@JavaScript.type()attribute with valuesType.SCRIPT(default, current behavior) andType.MODULE(new, renders<script type="module">). Source-compatible: existing@JavaScriptannotations keep their previous behavior.META-INF/resources/frontend/: once-per-jar build-time WARN "Addon '' contains frontend sources underMETA-INF/resources/frontend/. This location is deprecated; migrate them toMETA-INF/frontend/(bundle sources for@JsModule/@CssImport) or toMETA-INF/resources/(runtime resources for@StyleSheet/@JavaScript)." Still works. Split:@JsModule/@CssImport) → move toMETA-INF/frontend/.@StyleSheet/@JavaScript) → move toMETA-INF/resources/(drop thefrontend/segment, adjust annotation values accordingly).References
#22888, #23326, #16780 and the v25 web-component-path / CSS-loading forum threads.