Overview of Embedding Applications

How to embed an application in a web page.

Embedding Applications in Vaadin
Topics

In addition to running Vaadin as an application in a web page, you can embed it in a web page which could be part of some other application. Embedding applications is an alternative to writing monolithic frontends for your applications.

Embedded applications are also known as micro frontends. They are isolated and self-contained pieces of code that can be maintained by different teams, using different frameworks. A simple example is an embedded calendar in a web page. The calendar functionality is isolated and has no relation to the logic of the main application.

Embedding an application is similar to adding a client-side widget to a page. The difference is that the embedded application has backend logic and is a real application in its own right.

Embedding Applications in Vaadin

Vaadin allows you to embed applications using Web Components and provides the WebComponentExporter class for this purpose.

These are the basic steps to creating an embedded application:

Create the application that is embedded and export it: Write and declare a server-side component in a specific way, using a custom element tag name; and create an exporter for the component by extending the WebComponentExporter class.
Embed and use the application in your host (embedding) page. Make your page aware of the application by adding an element with a matching custom tag.

The embedded application behaves like a standard Vaadin component, regardless of any other content on the page, except that certain features aren’t available. See Embedded Application Limitations for more.

Creating an Embedded Application

To create an embedded application, you need to export a component as an embeddable application:

Create the component (MyComponent) that is used as the embedded application. You can create a new component or use an existing one. This component (application) has no relation to the host application.
Create an exporter for the component, by extending the WebComponentExporter<MyComponent> class. — Implement its constructor, providing the tag name that you use to identify it on the host application. — Configure properties in the constructor using the addProperty() method. — Implement the configureInstance() method, if you need additional initialization of the exported component (for example, add a listener to the original component).
Deploy your embeddable application.

See Creating an Embedded Vaadin Application Tutorial for a detailed example.

Importing an Embeddable Application

To embed the exported application in a page, import the web component URL resource of the embedded application; for example, <script type='module' src='YOUR_EMBEDDED_APPLICATION_URI/web-component/my-component.js'></script>.

The application is imported using the path "web-component/my-component.js", where "web-component" is the base path for embeddable applications, and "my-component.js" is the custom-tag-name.js.

YOUR_EMBEDDED_APPLICATION_URI is the URI at which you deploy your exported application. This depends on how and where you deploy the application.

Use the embedded web component in your HTML code by using the tag name you assigned to the embedded application; for example, <my-component></my-component>`.

The tag name, "my-component", is used to identify the embedded application. The element my-component is used in your HTML page content. This can be a static HTML file or content generated by any framework; for example, a plain servlet, JSP, and more.

Note

Generated Tag Name Represents a Web Component

The generated custom-tag-name ("my-component" in the example) element is a Web Component which wraps the original MyComponent HTML representation element. This element is inside the wrapper’s shadow root and isn’t available outside it. Hence, its styles don’t leak to the page, and global page styles don’t affect the styles of the embedded component.

The embeddable applications can also be used inside React views in Hilla applications, see Use Custom Flow Components In Hilla

Using External Embeddable Applications

If you use an embedded application that you develop in your own web application on the same domain, the preceding information is enough to make it work. However, the situation is different if you are developing an embeddable application to be deployed to a domain that differs from the domain of the main/embedding application. In this case, there is a cross-site cookies issue.

Like other servlet applications, Vaadin applications use cookies to track the HTTP session by default. For some cases, cross-site cookies can’t be used for embedding. In these cases, SSL session tracking mode can be used to get the embedded application to work.

To make embedded applications work, configure the server on which you are going to deploy the embeddable application to use HTTPS/SSL. The procedure for doing this is specific to each web server, so it’s out of the scope of this tutorial. Check the documentation of the server that you use. Then configure the embeddable application to use SSL session tracking mode.

@WebListener
public class SessionTrackingModeListener implements ServletContextListener {

    @Override
    public void contextDestroyed(ServletContextEvent event) {
    }

    @Override
    public void contextInitialized(ServletContextEvent event) {
        ServletContext context = event.getServletContext();
        EnumSet<SessionTrackingMode> modes = EnumSet
                .of(SessionTrackingMode.SSL);

        context.setSessionTrackingModes(modes);
    }

}

Lastly, use HTTPS protocol for links to your embeddable application. This means that the main/embedding application should use links with a format such as https://YOUR_DOMAIN:443/VAADIN/web-component/my-component.js. Use a similar pattern for other links.

Note

Session tracking mode switch is needed only in production. You probably don’t need to perform these steps during application development. In your tests, you normally use localhost as a local domain. Hence, there aren’t any issues with plain cookies session tracking mode. The session tracking mode switch is required only in production.

You can use a web.xml file and read session context initialization parameters from there in SessionTrackingModeListener code to switch the session tracking mode conditionally. You use the init parameter in web.xml to set one value for development mode, and another for production mode.

Topics

Tutorial: Creating a basic embedded application with Vaadin Flow.
Application Properties: How to set properties of embedded applications.
Theming: How to theme an embedded application.
Configuring Push: How to configure push in an embedded application.
Security: How to use an embedded application's properties to secure it.
Preserve on Refresh: How to preserve content when an embedded application is refreshed.
Limitations: List of limitations in embedded applications.

Docs