Skip to content

docs: note that @JavaScript honors runtime URL prefixes #6463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
vaadin-bot wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: note that @JavaScript honors runtime URL prefixes #6463

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions articles/flow/advanced/loading-resources.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,11 @@ Lit templates should be imported using `@JsModule` (see <</flow/component-intern
`@JavaScript`::
Defines a JavaScript file dependency. The file is loaded according to the load mode, as described in <<flow.loading-resources.load-mode>>.
+
By default, this renders a classic `<script>` element. Set the `type` attribute to `JavaScript.Type.MODULE` to render a `<script type="module">` element instead. A `type = JavaScript.Type.MODULE` file is always loaded at runtime and never bundled, even for a bare relative path, which is then resolved against the servlet context root. Use it for hand-authored or CDN-hosted ES modules that shouldn't go through Vite; for build-time bundled ES modules, use `@JsModule` instead. `LoadMode.INLINE` isn't supported in combination with `JavaScript.Type.MODULE`.
A value with a runtime prefix -- `context://`, `base://`, a leading `/`, `http://`, `https://`, `//`, or any other URL scheme -- is never bundled. It's loaded at runtime instead, the same way as the [methodname]`addJavaScript(String url)` method in [classname]`Page`. By default, this renders a classic `<script>` element. Set the `type` attribute to `JavaScript.Type.MODULE` to render a `<script type="module">` element instead. Use a runtime-prefixed value for hand-authored or CDN-hosted scripts that shouldn't go through Vite.
+
Any other, bare relative value is interpreted as relative to the `frontend` directory and bundled, behaving exactly as `@JsModule`. This bundled interpretation of `@JavaScript` is deprecated: use `@JsModule` with the same value to keep bundling the file, or move the file to a static location and reference it with a runtime prefix (or `JavaScript.Type.MODULE`) to load it at runtime instead.
+
`LoadMode.INLINE` isn't supported in combination with `JavaScript.Type.MODULE`.

`@CssImport`::
Imports a style sheet from an npm package, which it can be included in the frontend bundle.
Expand Down Expand Up @@ -292,7 +296,7 @@ Resources can be loaded as individual files or included in the frontend bundle t

Vaadin bundles all of the web components used in an application into a single frontend bundle file, which can be loaded efficiently when the application page is loaded. You can include your own files into the bundle, as well.

Static resources that are bundled using Vite and referenced with the `@JavaScript`, `@JsModule`, and `@CssImport` annotations should be placed under `{project directory}/frontend`. This includes normal JavaScript and TypeScript files, Lit template files, and CSS files.
Static resources that are bundled using Vite and referenced with the `@JavaScript`, `@JsModule`, and `@CssImport` annotations should be placed under `{project directory}/frontend`. This includes normal JavaScript and TypeScript files, Lit template files, and CSS files. For `@JavaScript`, only a bare relative value (one without a runtime prefix) is bundled this way, and that interpretation is deprecated -- use `@JsModule` instead for files that should be bundled.

When importing files using these annotations, prefix the path with `./`, which signifies the `frontend/` directory. For example, a CSS file [filename]`my-custom.css` under [filename]`{project directory}/frontend/styles/my-custom.css` would be referenced `@CssImport("./styles/my-custom.css")`.

Expand Down
Loading