Repository navigation
docs: document on-demand chunk loading and dynamic imports under strict CSP - #6554
Conversation
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`).
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6554.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from aa1712b |
…6813-08aa8769e8eb325a # Conflicts: # articles/flow/security/advanced-topics/strict-csp.adoc
heruan
left a comment
There was a problem hiding this comment.
Checked against Page.addDynamicImport(JsFunction) on Flow main: the blocking behavior, the single load for equal captured values, the IllegalArgumentException for captured elements and the unsafe-eval note on the string overload are all correct. Removing the chunk loader entry from the recipe is also correct since vaadin/flow#26813.
The failed build-and-deploy check is a preview deploy error (connection lost while building the image), not a content problem.
| } | ||
| ---- | ||
|
|
||
| The path given to `import()` must be a literal string for the bundler to split it into a file of its own, and the imported component must not also carry [annotationname]`@JsModule` for the same file, or the module ends up in the main bundle instead. |
There was a problem hiding this comment.
I could not verify the second half of this sentence: that a @JsModule for the same file moves the module into the main bundle. It sounds right, but it is not in the Javadoc and I did not test it. Could someone who knows the bundler confirm it? Not a blocker.
There was a problem hiding this comment.
@heruan That half was not accurate for lazy routes: their @JsModule files go into the route's own chunk, not the main bundle. The sentence now says that Flow loads the module with the chunk of the view that uses the component, so the dynamic import no longer controls when it loads.
vaadin-review-bot
left a comment
There was a problem hiding this comment.
Reviewed the changes — left 4 comments.
| Finding | |
|---|---|
The reason given for not adding @JsModule to the component is wrong for a lazily loaded route. |
|
| 💬 | The Frontend/ import prefix is unexplained and contradicts the ./ rule stated twice on the same page. |
| 💬 | @JsDefinition, @JsExpression and JsSnippets are used without a link to the page that explains them. |
| 📐 | The new section documents a 25.4 API with no since badge. |
| } | ||
| ---- | ||
|
|
||
| The path given to `import()` must be a literal string for the bundler to split it into a file of its own, and the imported component must not also carry [annotationname]`@JsModule` for the same file, or the module ends up in the main bundle instead. |
There was a problem hiding this comment.
@JsModule to the component is wrong for a lazily loaded route.
"the imported component must not also carry [annotationname]
@JsModulefor the same file, or the module ends up in the main bundle instead"
Flow only puts @JsModule files into the main bundle when the entry point that reaches them is eager. A route is lazy unless marked eager (FrontendDependencies.java:545), and the files of a lazy route go into a chunk-<hash>.js of their own, loaded on demand (AbstractUpdateImports.java:390-396, 541-547). So for a component reached only from a normal route, adding @JsModule puts the module in that route's chunk, not in the main bundle, and it makes the manual dynamic import redundant rather than useless.
Suggested rewrite: "The imported component must not also carry [annotationname]@JsModule for the same file. Flow then loads the module itself, with the chunk of the view that uses the component, and the dynamic import no longer controls when it loads."
loading-resources.adoc:214 · accuracy
There was a problem hiding this comment.
Rewrote the sentence: if the component also carries @JsModule, Flow loads the module with the chunk of the view that uses the component, and the dynamic import no longer controls when it loads. The "ends up in the main bundle" claim is gone.
| ---- | ||
| @JsDefinition | ||
| public interface ReportEditorJs extends Serializable { | ||
| @JsExpression("return import('Frontend/report-editor/report-editor.js');") |
There was a problem hiding this comment.
💬 The Frontend/ import prefix is unexplained and contradicts the ./ rule stated twice on the same page.
@JsExpression("return import('Frontend/report-editor/report-editor.js');")
The same page tells readers twice to use ./ for the frontend directory (lines 98 and 337). A reader who follows that here and writes ./report-editor/report-editor.js gets a broken import: the build writes the declared expression into [filename]frontend/generated/vaadin-js-definitions.js (FrontendUtils.GENERATED + JS_DEFINITIONS_FILE_NAME), so a relative path resolves against frontend/generated/, not frontend/. Frontend is a Vite alias for the frontend folder (vite.generated.ts:551).
Add a sentence after the first example, for example: "The Frontend/ prefix resolves against the frontend directory. A relative path can't be used here, because the build writes the declared expression into a generated file under frontend/generated."
loading-resources.adoc:197 · clarity
There was a problem hiding this comment.
Added a sentence after the interface example: the Frontend/ prefix resolves against the frontend directory, and a relative path can't be used because the build writes the expression into a generated file under frontend/generated.
|
|
||
| Use [methodname]`addDynamicImport(JsFunction)` to load JavaScript whose `Promise` must resolve before anything else changes on the page -- a web component module that's kept out of the main bundle and loaded only when it's first needed, for example. No later change in the same round trip is applied until the `Promise` resolves. | ||
|
|
||
| Declare the import as a method of a [annotationname]`@JsDefinition` interface and obtain it through [classname]`JsSnippets`, so that loading it compiles nothing in the browser, and the call keeps working under a content security policy that doesn't allow `unsafe-eval` (see <<{articles}/flow/security/protections/content-security-policy#,Content Security Policy>>): |
There was a problem hiding this comment.
💬 @JsDefinition, @JsExpression and JsSnippets are used without a link to the page that explains them.
"Declare the import as a method of a [annotationname]
@JsDefinitioninterface and obtain it through [classname]JsSnippets"
The only link is to the CSP page, which doesn't explain these types either. A reader meeting them here can't tell what an interface must look like, and JsSnippets appears nowhere else in the documentation.
The sibling page does this already — browser-access.adoc:114 ends with "What such an interface may contain is described in <</flow/component-internals/element-api/calling-javascript#declaring-javascript,Declaring JavaScript in Java>>". Add the same link here.
Worth asking too: JsSnippets.of() is the general way to declare a [classname]JsFunction in the bundle, and calling-javascript.adoc owns both @JsDefinition and JsFunction. Should that mechanism be documented there, with this section linking to it?
loading-resources.adoc:191 · clarity
There was a problem hiding this comment.
Added the same link as the browser-access page, to Declaring JavaScript in Java on the calling-javascript page. Documenting JsSnippets.of() as a general mechanism there would be a separate change, so I left it out of this PR.
| ---- | ||
|
|
||
|
|
||
| === Dynamic Imports |
There was a problem hiding this comment.
📐 The new section documents a 25.4 API with no since badge.
addDynamicImport(JsFunction), @JsDefinition and JsSnippets are all @since 25.4 in Flow. CONVENTIONS.md under "Versions" says: "Mark new features with a since badge instead: the [role="since:com.vaadin:vaadin@V25.2"] attribute above a section heading".
The sibling sections for the same release carry it — see browser-access.adoc:111 and calling-javascript.adoc:21. Since the addDynamicImport(String) overload is old, the badge may fit better on the paragraph than on the heading.
loading-resources.adoc:187 · conventions
There was a problem hiding this comment.
Added a 25.4 since badge as an inline span on addDynamicImport(JsFunction) rather than on the heading, since the string overload is older.
|
@totally-not-ai Address the review comments of this PR. |
|
@heruan Addressed all review comments in the latest commits (replies inline). The failed |
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
articles/flow/advanced/loading-resources.adocPage.addDynamicImport(JsFunction)overload: how to declare the import, the bundler-splitting requirement, the element-capture restriction, and how it relates to the existingaddDynamicImport(String)overload.articles/flow/security/protections/content-security-policy.adocloadOnDemandstring-matching branch from the override code sample.Auto-generated by the Documentation Bot — review before merging.