Embedded Application Limitations

Some Vaadin features are not available in embedded applications.

Limitations in embedded applications include:

  • Navigation and routing: Both features are not available for embedded applications.

    • There is no point annotating your classes with the@Route annotation, because it is not possible to navigate to the route target.

    • You can also not use the router link, whether via the RouterLink class or in a custom way.

  • Theming: You can only specify one @Theme annotation. See Theming Embedded Applications for more.

  • Push: You can only use one @Push annotation. See Configuring Push in Embedded Applications for more.

  • Progressive Web Applications: @PWA annotation and all PWAs features are not available in embedded applications.

  • Cross-site embedding: any Vaadin application is a Java Servlet based application. Java Servlet applications use cookies to store a session id. Sometimes some browsers (e.g. Safari) don’t allow to use cookies for embedded page if it has a different domain. In this case embedding requires SSL tracking mode to work. Please refer to Overview of Embedding Applications Using an external Embeddable Application section how to configure embedded application to work in this case.

  • CORS headers: Cross-Origin Resource Sharing (CORS) headers are not defined automatically. If the Vaadin servlet providing the embeddable application is outside of the servlet container that provides the page in which it is embedded, these headers need to be provided.

    The responses from the Vaadin servlet should contain appropriate CORS headers. You can add these by:

    • Configuring the servlet container (see the documentation on adding HTTP headers for responses for your specific container), or

    • Packaging the embeddable application with a custom VaadinServlet.

      Example: Custom VaadinServlet that adds CORS headers

      public class CustomServlet extends VaadinServlet {
          public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
              setAccessControlHeaders((HttpServletResponse) res);
              super.service(req, res);
          private void setAccessControlHeaders(HttpServletResponse resp) {
              resp.setHeader("Access-Control-Allow-Origin", "http://localhost:80");
              resp.setHeader("Access-Control-Allow-Methods", "*");
              resp.setHeader("Access-Control-Allow-Headers", "Content-Type");
              resp.setHeader("Access-Control-Allow-Credentials", "true");
      • This example assumes that the embedding (host) site is served from the same host mapped to port 80 (be it a servlet container or a custom Python HTTP server). Our servlet container with our Vaadin servlet is bound to, for example, 8080.

  • Theme resources should be available on the server of the embedding page or embedded in CSS (as data URLs).

    When embedding the application on a different server, relative CSS URLs target the embedding server and not the embedded application server.

    Retrieve the target server address from the request as follows:

StringBuffer requestURL = ((HttpServletRequest) VaadinRequest.getCurrent()).getRequestURL();

Then you can prepend that to the resource URL. For example:

new Image(requestURL.toString() + "themes/app-theme/img/logo.png", "logo");