Repository navigation
feat: load on-demand chunks without compiling JavaScript - #26813
Conversation
Chunk loading sent "return window.Vaadin.Flow.loadOnDemand('<id>');"
as a dynamic import expression, which the client compiled with
new Function, so a route with a lazily loaded chunk could not be
opened under a Content Security Policy without 'unsafe-eval'.
A dynamic import can now carry a JsFunction. Flow declares the chunk
loader as a bundled snippet, the server sends it as a @v-fn value in
the dependency url, and the client decodes and calls it instead of
compiling a string. Page.addDynamicImport(JsFunction) gives
applications the same CSP-safe option.
Fixes #26150
Memory footprintCompared with the base commit cda10ef.
Empty UI: Heap retained per UI by class
UI with 200 component rows: Heap retained per UI by class
UI with 200 form rows added in the latest round trip: Heap retained per UI by class
UI with 200 form rows: Heap retained per UI by class
Scenarios
Measured by |
Decode a dynamic import function when it is loaded, so a capture the client cannot resolve yet fails that import through its listener instead of dropping the whole message. Document that captures cannot refer to elements attached in the same round trip, and that a dependency filter has to return a function-backed dynamic import as the same instance. Add tests for de-duplication and serialization of function-backed dynamic imports.
|
Fixed the three issues: |
|
|
||
| Collection<Dependency> dependencies = ui.getInternals() | ||
| .getDependencyList().getPendingSendToClient(); | ||
| assertEquals(2, dependencies.size()); |
There was a problem hiding this comment.
The test verifies that only two dependencies will be sent but does not actually check if they are exactly a and b.
There was a problem hiding this comment.
@mcollovati The test now reads the captures of the pending dependencies and asserts they are exactly a and b, in that order.
| this.dynamicImport = Objects.requireNonNull(dynamicImport, | ||
| "dynamicImport cannot be null"); | ||
| this.url = JacksonUtils.getMapper().writeValueAsString( | ||
| JacksonCodec.encodeWithTypeInfo(dynamicImport)); |
There was a problem hiding this comment.
Do we really need to keep both the JsFunction and its JSON representation in url?
Can we make the encoded JSON in url the only source of truth?
This should avoid the need to "Return a {@link Dependency.Type#DYNAMIC_IMPORT} dependency as the same instance rather than as a copy" in DependencyFilter.
Also, DependencyList makes a copy of Dependency using a constructor that is not aware of the JsFunction, so it might create a potentially incorrect copy.
There was a problem hiding this comment.
@mcollovati Agreed. Dependency no longer stores the JsFunction: the encoded JSON in url is the only source of truth, and getEncodedDynamicImport() reads it back from the url when the type is DYNAMIC_IMPORT and the url starts with {"@v-fn":. No JavaScript expression can start like that, because it does not compile as a function body, so a string expression is never mistaken for a function. A copy made from type and url, such as the one DependencyList makes for a load mode conflict or one a filter makes, now still loads the function, so I removed the DependencyFilter note. DependencyTest covers the copy.
| * A function that is added again with the same captured values is loaded | ||
| * only once. The function is created when the dependencies are processed in | ||
| * the browser, before the changes of the same round trip are applied, so it | ||
| * cannot capture an element that is attached in that round trip. |
There was a problem hiding this comment.
If there is such a limitation with element capture, it would be better to immediately reject them throwing an exception.
There was a problem hiding this comment.
@mcollovati Done. new Dependency(JsFunction), and so Page.addDynamicImport(JsFunction), now throws IllegalArgumentException if a capture encodes an element (@v-node at any depth). The check runs on the encoding the constructor already does, and the Javadoc documents the @throws. Detached elements already encode as null, so the check only rejects attached ones, which the browser cannot resolve yet when it loads dependencies.
| chunkIds.forEach(chunkId -> ui.getPage() | ||
| .addDynamicImport(CHUNK_JS.loadChunk(chunkId))); |
There was a problem hiding this comment.
Using the JsFunction to load import has an additional cost of a proxy call plus JSON encode.
Probably, this is not so relevant in terms of performance, but it would be worth to check.
There was a problem hiding this comment.
@mcollovati I measured it with a quick JVM loop. Creating the chunk dependency through the snippet took about 0.7 µs, against about 15 ns for the old string concatenation. Chunk loading runs for each component class on every response that attaches components, so UIInternals now creates the dependency once per chunk id, in a static map. The map holds only strings and is bounded by the number of chunks, and the dependency is immutable, so it is safe to share. With the cache, a repeated add costs about 60 ns, against about 95 ns for building the string each time. Reading the function back for the UIDL is a JSON parse of about 0.6 µs, once per chunk sent to a UI.
The encoded function in the url is now the only source of truth, so a copy of the dependency made from its type and url, as DependencyList and dependency filters make, still loads the function. A function that captures an element is rejected when it is added, as the browser loads dependencies before it creates the elements of the same round trip. Chunk dependencies are created once per chunk instead of once per response that attaches a component.
There was a problem hiding this comment.
Is it so that this test class is missing tests for the DYNAMIC_IMPORT JSON encoding?
There was a problem hiding this comment.
@mcollovati Yes, it only covered the chunk case, through getChunkIds. I added dynamicImports_expressionSentAsString_functionSentAsValue. It adds one string expression and one JsFunction through Page.addDynamicImport, then asserts that the LAZY dependencies of the response carry exactly the expression as a JSON string and the function as its @v-fn encoding, in that order.
Chunk loading now sends a function value instead of a string expressionflowchart LR
subgraph Before
direction TB
B1["UIInternals.triggerChunkLoading builds loadOnDemand(id) string"] -->|"new Dependency(Type, String)"| B2["Dependency stores expression as url"]
B2 -->|"UidlWriter writes url"| B3["UIDL url is the expression string"]
B3 -->|"DependencyLoader reads url"| B4["ResourceLoader.loadDynamicImport"]
B4 -->|"new Function(expression)"| B5["browser compiles and runs string"]
end
subgraph After
direction TB
A1["UIInternals.triggerChunkLoading calls ChunkJs.loadChunk(chunkId)"]:::changed -->|"new Dependency(JsFunction)"| A2["JacksonCodec.encodeWithTypeInfo(function)"]:::changed
A2 -->|"UidlWriter writes url"| A3["UIDL url is the encoded function JSON"]:::changed
A3 -->|"DependencyLoader decodes url"| A4["ClientJsonCodec.decodeWithTypeInfo"]:::changed
A4 -->|"ResourceLoader.loadDynamicImport(load)"| A5["given function runs, nothing compiled"]:::changed
end
Before ~~~ After
classDef changed stroke:#c9a227,stroke-width:3px
Diagram Bot draws the mechanism this pull request touches; it does not review the change. Verify it against the diff.
|
vaadin-review-bot
left a comment
There was a problem hiding this comment.
Reviewed the changes — left 2 comments.
| Finding | |
|---|---|
| 🧪 | The @v-node guard on the encoded JSON has no test |
| 📝 | The documented IllegalArgumentException does not cover a detached element inside a bean |
| JsonNode encoded = JacksonCodec.encodeWithTypeInfo(dynamicImport); | ||
| // How JacksonCodec references an attached element, such as one in a | ||
| // bean property, which capturesElement does not look into | ||
| if (encoded.findValue("@v-node") != null) { |
There was a problem hiding this comment.
🧪 The @v-node guard on the encoded JSON has no test
All five rejection cases in PageTest (element, detached element, component, element in a list, element in a nested function) are already caught by capturesElement before encoding happens. Nothing captures an attached element reached only through a bean property, which is the single case this second check exists for — delete it and the suite still passes.
Dependency.java:219 · tests
There was a problem hiding this comment.
Added addDynamicImportFunction_attachedElementInBean_throws. It captures a record that holds an attached element, which capturesElement does not look into, so only the check on the encoded @v-node rejects it. I confirmed that the test fails with that check disabled.
| * @param dynamicImport | ||
| * the function that returns a Promise, not {@code null} | ||
| * @throws IllegalArgumentException | ||
| * if the function captures an element or a component |
There was a problem hiding this comment.
📝 The documented IllegalArgumentException does not cover a detached element inside a bean
capturesElement walks captures, collections, maps, arrays and nested functions, but not bean properties, and NodeSerializer writes a detached node as null, so neither check fires. The capture is accepted and silently arrives as null on the client. Either qualify the wording in both Page.addDynamicImport(JsFunction) and Dependency(JsFunction), or make the check see into beans.
Page.java:483 · documentation
There was a problem hiding this comment.
I qualified the wording rather than walking bean properties. Walking them would duplicate what Jackson already does to serialize the bean, and other values sent to the browser treat a detached element in a bean the same way. Page.addDynamicImport(JsFunction) now says the check covers a capture itself and what a collection, map, array or captured function holds. It also says bean properties are only checked for attached elements, and that a detached one in a bean is sent as null, as it is for any other value sent to the browser. The @throws of Dependency(JsFunction) lists the same cases.
|
Fixed the |
|
|
||
| private static final ChunkJs CHUNK_JS = JsSnippets.of(ChunkJs.class); | ||
|
|
||
| // Bounded by the number of chunks, and holds only strings |
There was a problem hiding this comment.
| // Bounded by the number of chunks, and holds only strings | |
| // One entry per chunk id, which is per component class name in development | |
| // mode. |
There was a problem hiding this comment.
@mcollovati Applied the suggested comment.
|
Document Page.addDynamicImport(JsFunction) for CSP-safe lazy loading of JavaScript modules, and note that loading a route's on-demand chunk no longer needs the Function-override workaround on the strict CSP page. Documents vaadin/flow#26813 (`eb003c0838d5063b1e4a5d607da59bd6fc536c60`).
|
Pull request created: #6554
|
|
Documentation Bot: Draft documentation pull request for this change: vaadin/docs#6554 Files updated:
It was written from the state of this pull request as you see it now. Please review it and mark it ready for review.
|
|
This ticket/PR has been released with Vaadin 25.4.0-alpha5. |
…ct CSP (#6554) Documentation for vaadin/flow#26813 by `@totally-not-ai`[bot]. > [!NOTE] > The source pull request is merged, so this documentation describes the final > shape of the change. Please review it and mark it ready for review. **Change categories:** NEW_FEATURE, API_CHANGE, BEHAVIOR_CHANGE | File | Change | |------|--------| | `articles/flow/advanced/loading-resources.adoc` | Added a "Dynamic Imports" subsection documenting the new `Page.addDynamicImport(JsFunction)` overload: how to declare the import, the bundler-splitting requirement, the element-capture restriction, and how it relates to the existing `addDynamicImport(String)` overload. | | `articles/flow/security/protections/content-security-policy.adoc` | Removed "chunk loading" from the list of things the nonce-only example doesn't handle, added a sentence noting that a route's on-demand chunk no longer needs the Function-override workaround, and removed the now-dead `loadOnDemand` string-matching branch from the override code sample. | Auto-generated by the Documentation Bot — review before merging. > Generated by [Documentation Bot](https://github.com/vaadin/flow/actions/runs/41685202669) for #26813 · agent · 126.7 AIC · ⊞ 11.7K · [◷](https://github.com/search?q=repo%3Avaadin%2Fdocs+%22gh-aw-workflow-id%3A+doc-bot%22&type=pullrequests) > - [x] expires <!-- gh-aw-expires: 2026-12-03T17:41:02.724Z --> on Dec 3, 2026, 5:41 PM UTC <!-- gh-aw-agentic-workflow: Documentation Bot, engine: claude, model: agent, id: 41685202669, workflow_id: doc-bot, run: https://github.com/vaadin/flow/actions/runs/41685202669 --> <!-- gh-aw-expires-type: pull-request --> <!-- gh-aw-workflow-id: doc-bot --> <!-- gh-aw-workflow-call-id: vaadin/flow/doc-bot --> --------- Co-authored-by: totally-not-ai[bot] <290682512+totally-not-ai[bot]@users.noreply.github.com>



Review risk: two-way door — changes how every route's chunk is loaded on the client (wire form of
DYNAMIC_IMPORTfor Flow's own chunks); stringaddDynamicImportcalls are unchanged.Fixes #26150
Summary
Opening a route whose JavaScript is in a lazily loaded chunk made the browser compile a string sent by the server, which a Content Security Policy without
unsafe-evalblocks. Chunk loading now uses a function declared in the bundle (as added in #26729), so nothing is compiled in the browser. Applications get the same option through a newPage.addDynamicImport(JsFunction)overload. The blocking behaviour is unchanged: no later change is applied until the chunk promise resolves.What changed
UIInternalsdeclares the chunk loader as a@JsDefinitionsnippet (ChunkJs.loadChunk(chunkId)) and passes it toPage.addDynamicImport(JsFunction)instead of building theloadOnDemand('<id>')expression string. InstrictCSP mode, navigating to a route no longer throws.Page.addDynamicImport(JsFunction); theStringoverload's Javadoc points to it as the CSP-safe alternative.Dependencygets an internal constructor that takes aJsFunction. Itsurl, which de-duplicates dependencies, is the JSON of the encoded function and the only place the function is kept, so the same function with the same captures loads once and a copy made from type andurl(asDependencyListand dependency filters make) still loads the function. The internalgetEncodedDynamicImport()reads it back from theurl; no JavaScript expression starts like that JSON, as it would not compile as a function body.UidlWritersends such a dependency with the encoded@v-fnvalue inurlinstead of a string. The message shape is otherwise the same.DependencyLoaderdecodes an objecturlof aDYNAMIC_IMPORTwithClientJsonCodecand passes the function toResourceLoader.loadDynamicImport, which calls it instead ofnew Function. String expressions keep the old path. Waiting, listeners and error reporting are unchanged; a function missing from the bundle fails the import through the existing error path.urlof a chunk-loading dependency in the UIDL JSON is now an object, not a string. A customDependencyFiltersees aDependencywhosegetUrl()is that JSON string.IllegalArgumentExceptionwhen it is added: the browser loads dependencies before it applies the changes of the same round trip, and a detached element is encoded asnull, so it cannot be referenced. The check looks at the Java captures, including collections, maps, arrays and nested functions, and at the encoded JSON for an attached element inside a bean. On the client the function is decoded when the import is loaded, so a value that cannot be decoded fails only that import through its listener instead of the whole message.Use case
A reporting view has an "Advanced editing" mode backed by a large
<report-editor>web component that most users never open. Its module is kept out of the initial bundle and loaded only on first use; because the import blocks the rest of the round trip, the element is already defined when Flow attaches it, and nothing is compiled from a string, so it works under a CSP withoutunsafe-eval:ReportEditormust not also carry@JsModulefor the same file, or the module ends up in the main bundle. The path has to be a literal for the bundler to split it.Test summary
strictCSP test checks that loading a route's chunk no longer throws (it failed with the old string expression).DYNAMIC_IMPORTwhose copy from type andurlstill carries the function; a function capturing an element is rejected, whether the element is attached, detached, a component, or inside a list or a nested function.@v-fnis decoded from the snippet registry and called; a function that cannot be decoded fails only that import;loadDynamicImportcalls a given function without compiling the expression.JsFunctionITend to end in a browser (passes), and checked that the generatedvaadin-js-definitions.jscontains the chunk loader.API Changes
Working on behalf of @mcollovati