Package com.vaadin.flow.component.dependency

Annotation Interface JavaScript

@Retention(RUNTIME) @Target(TYPE) @Inherited @Documented @Repeatable(Container.class) public @interface JavaScript
Defines JavaScript dependencies on a Component class. For adding multiple JavaScript files for a single component, you can use this annotation multiple times.

It is guaranteed that dependencies will be loaded only once. The files loaded will be in the same order as the annotations were on the class. However, loading order is only guaranteed on a class level; Annotations from different classes may appear in different order, grouped by the annotated class. Also, files identified by @JavaScript will be loaded after JsModule and before CssImport.

NOTE: Bundled frontend resources are combined into one big bundle. This means, that a bundled JavaScript file loaded by one class will be present on a view constructed by another class. For example, if there are two classes RootRoute annotated with @Route(""), and another class RouteA annotated with @Route("route-a") and @JavaScript("./src/javascript.js"), the javascript.js will be run on the root route as well. This does not apply to resources loaded at runtime, such as a @JavaScript with type() set to JavaScript.Type.MODULE, which are loaded per page and never bundled.

External JavaScript dependencies (e.g. "http://example.com/some.js") are added in the same way as Page.addJavaScript(String) and the result is just adding a classic script element to the page. Other paths used in the value() method are considered as relative to frontend directory and they are bundled and added to the page as a JavaScript module (a script element with type="module"). In this case a JavaScript annotation behaves exactly as a JsModule annotation.

Setting type() to JavaScript.Type.MODULE opts out of that bundling: the file is then always loaded at runtime as a script element with type="module", even when the value is a bare relative path, which is resolved against the servlet context root. Use it for hand-authored or CDN-hosted ES modules that should not go through Vite; for build-time bundled ES modules use JsModule instead.

It's not possible to execute a function defined in JavaScript module via 


 
 UI.getCurrent().getPage().executeJs("some_function_definied_in_module()");
because the function is private there (unless it's explicitly exposed). The JavaScript where the function is defined should be either external or it should be added using Page.addJavaScript(String): in this case all declared functions become available in the global scope.
Since:
1.0
Author:
Vaadin Ltd
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    JavaScript.Container
    Internal annotation to enable use of multiple JavaScript annotations.
    static enum 
    JavaScript.Type
    The kind of <script> tag to render for the dependency.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    JavaScript file URL to load before using the annotated Component in the browser.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    developmentOnly
    Defines if the JavaScript should be loaded only when running in development mode (for development tooling etc.) or if it should always be loaded.
    LoadMode
    loadMode
    Determines the dependency load mode.
    JavaScript.Type
    type
    The kind of <script> tag to use when loading the file.

  • Element Details

    • value

      String value
      JavaScript file URL to load before using the annotated Component in the browser.

      Relative URLs are interpreted as relative to the configured frontend directory location.

      This URL identifies a file which will be bundled, so the file should be available to be able to bundle it.

      You can prefix the URL with context:// to make it relative to the context path or use an absolute URL to refer to files outside the frontend directory. Such URLs are not bundled but included into the page as standalone scripts in the same way as it's done by Page.addJavaScript(String).

      When type() is JavaScript.Type.MODULE, the value is loaded at runtime regardless of whether it has a URL prefix; bare relative paths are normalized to context://<value> and served as static resources by the servlet container.

      Returns:
      a JavaScript file URL

    • type

      JavaScript.Type type
      The kind of <script> tag to use when loading the file. Defaults to JavaScript.Type.SCRIPT (a classic <script> element). Set to JavaScript.Type.MODULE to render a <script type="module"> element instead, e.g. for hand-authored or CDN-hosted ES modules that should not go through Vite. For build-time bundled ES modules use JsModule instead.
      Returns:
      the kind of script tag to render
      Since:
      25.4
      Default:
      SCRIPT

    • developmentOnly

      boolean developmentOnly
      Defines if the JavaScript should be loaded only when running in development mode (for development tooling etc.) or if it should always be loaded.

      By default, scripts are always loaded.

      Returns:
      true to load the script only in development mode, false to always load it
      Since:
      24.2
      Default:
      false

    • loadMode

      LoadMode loadMode
      Determines the dependency load mode. Refer to LoadMode for the details.

      LoadMode.INLINE cannot be combined with JavaScript.Type.MODULE; such a combination is rejected with an IllegalArgumentException when the dependency is added to the page.

      Returns:
      load mode for the dependency
      Default:
      EAGER