Search code examples
springpolymervaadinstylesheetvaadin-flow

Where should I place my Vaadin 10+ static files?

In Vaadin 10-14, where should I place my static files, such as CSS, JavaScript, and Polymer templates? How about static files such as images?

Also, how do I import these files in Vaadin? Is there a difference between Vaadin 14 with npm and Vaadin 10-13 with bower?

Solution

  • All paths are relative to the project root, e.g. where the pom.xml file is located in a Maven project.

    JavaScript imported using @JsModule uses strict mode. Among other things, this means that global variables must be defined on the window object, window.x = ..., instead of just x = ....

    Vaadin 14 with npm

    Non-Spring Boot projects (war packaging)

    • CSS files
      • @CssImport("./my-styles/styles.css")[1]
      • /frontend/my-styles/styles.css
    • JavaScript and Polymer templates
      • @JsModule("./src/my-script.js")[1]
      • /frontend/src/my-script.js
    • Static files, e.g. images
      • new Image("img/flower.jpg", "A flower")
      • /src/main/webapp/img/flower.jpg

    Spring Boot projects (jar packaging)

    • CSS files
      • @CssImport("./my-styles/styles.css")[1]
      • /frontend/my-styles/styles.css
    • JavaScript and Polymer templates
      • @JsModule("./src/my-script.js")[1]
      • /frontend/src/my-script.js
    • Static files, e.g. images
      • new Image("img/flower.jpg", "A flower")
      • /src/main/resources/META-INF/resources/img/flower.jpg

    Add-ons (jar packaging)

    • CSS files
      • @CssImport("./my-styles/styles.css")[1]
      • /src/main/resources/META-INF/resources/frontend/my-styles/styles.css
    • JavaScript and Polymer templates
      • @JsModule("./src/my-script.js")[1]
      • /src/main/resources/META-INF/resources/frontend/src/my-script.js
    • Static files, e.g. images
      • new Image("img/flower.jpg", "A flower")
      • /src/main/resources/META-INF/resources/img/flower.jpg

    Vaadin 10-13, Vaadin 14 in compatibility mode

    Non-Spring Boot projects (war packaging)

    • CSS files
      • @StyleSheet("css/styles.css")[2]
      • /src/main/webapp/frontend/css/styles.css
    • Polymer templates, custom-style and dom-module styles
      • @HtmlImport("src/template.html")
      • /src/main/webapp/frontend/src/template.html
    • JavaScript
      • @JavaScript("js/script.js")[3]
      • /src/main/webapp/frontend/js/script.js
    • Static files, e.g. images
      • new Image("img/flower.jpg", "A flower")
      • /src/main/webapp/img/flower.jpg

    Spring Boot projects and add-ons (jar packaging)

    • CSS files
      • @StyleSheet("css/styles.css")[2]
      • /src/main/resources/META-INF/resources/frontend/css/styles.css
    • Polymer templates, custom-style and dom-module styles
      • @HtmlImport("src/template.html")
      • /src/main/resources/META-INF/resources/frontend/src/template.html
    • JavaScript
      • @JavaScript("js/script.js")[3]
      • /src/main/resources/META-INF/resources/frontend/js/script.js
    • Static files, e.g. images
      • new Image("img/flower.jpg", "A flower")
      • /src/main/resources/META-INF/resources/img/flower.jpg

    Footnotes

    [1] The @JsModule and @CssImport annotations can also be used for importing from an npm package. In this case, the path is defined as @JsModule("@polymer/paper-input") or @CssImport("some-package/style.css"). Paths referring to the local frontend directory should be prefixed with ./

    [2] The @StyleSheet annotation can also be used in Vaadin 14 with npm. The same paths as in V10-V13 can be used, including the context:// protocol @StyleSheet("context://style.css"), which resolves the path relative to the context path of the web application, like other static files. Styles included this way may cause issues with web components.

    [3] The @JavaScript annotation can also be used in Vaadin 14 with npm. The V14 /frontend folder should then be used,.