Skip to content

docs: document on-demand chunk loading and dynamic imports under strict CSP - #6554

Merged
heruan merged 5 commits into
mainfrom
doc-bot/vaadin-flow/26813-08aa8769e8eb325a
Nov 19, 2026
Merged

heruan merged 5 commits into
mainfrom
doc-bot/vaadin-flow/26813-08aa8769e8eb325a

Conversation

@vaadin-bot

@vaadin-bot vaadin-bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

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 for #26813 · agent · 126.7 AIC · ⊞ 11.7K · ◷

  • expires on Dec 3, 2026, 5:41 PM UTC

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`).
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6554.fly.dev

Changed pages

Added 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
heruan marked this pull request as ready for review November 17, 2026 08:18

@heruan heruan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 vaadin-review-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ The reason given for not adding @JsModule to the component is wrong for a lazily loaded route.

"the imported component must not also carry [annotationname]@JsModule for 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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');")

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>>):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 @JsDefinition, @JsExpression and JsSnippets are used without a link to the page that explains them.

"Declare the import as a method of a [annotationname]@JsDefinition interface 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a 25.4 since badge as an inline span on addDynamicImport(JsFunction) rather than on the heading, since the string overload is older.

@heruan

heruan commented Nov 19, 2026

Copy link
Copy Markdown
Member

@totally-not-ai Address the review comments of this PR.

@totally-not-ai

Copy link
Copy Markdown
Contributor

@heruan Addressed all review comments in the latest commits (replies inline). The failed build-and-deploy run was a Fly.io connection drop during the image build, so I re-ran the failed job.

@heruan
heruan merged commit f254bf7 into main Nov 19, 2026
12 of 13 checks passed
@heruan
heruan deleted the doc-bot/vaadin-flow/26813-08aa8769e8eb325a branch November 19, 2026 09:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants