Customising Bundling

Defining Fragments

By default the plugin will bundle all front-end dependencies into a single html import that contains all dependencies and their transitive dependencies. To split this potentially large file up into several smaller files that can be served only as needed, the plugin can be configured to produce fragment files.

Fragments are html imports containing dependencies that have been split out of the main bundle file.

Basic principle is the same: you specify a files that should go into each fragment by giving their paths. The paths listed in a fragment should be given relative to the transpileEs6SourceDirectory you have configured, which is by default ${project.build.directory}/frontend/.

Note that any shared dependencies between multiple fragments will be detected and added to the main bundle file. Thus to effectively split your bundle into fragments, shared dependencies should be taken into account when defining the fragment split to use.

As a starting point for splitting a bundle into fragments it is recommended that you first run the plugin without any fragments defined and inspect the produced vaadin-flow-bundle.html file, which contains all the front-end dependencies found in your projects run time classpath. The produced bundle can be found in the location defined by the transpileWorkingDirectory parameter, which defaults to ${project.build.directory}/, i.e. target/ if the project build directory has not been configured separately.

When running a bundle enabled flow application in production mode a DependencyFilter is automatically registered during startup to serve the bundle and fragment files instead of their individual dependencies whenever requested.

Example bundle configurations will be shown for Maven and a Json configuration file.

The defined fragments are:

• A fragment containing only vaadin-icons

• A fragment containing several components

• A fragment containing vaadin-grid and its flow integration dependencies

Defining Fragments with Maven

Fragments are configured by adding <fragments> to the configuration of the plugin. Each fragment should have its name and at least one file specified.

pom.xml

<plugin>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-maven-plugin</artifactId>
    <version>${vaadin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>package-for-production</goal>
            </goals>
            <configuration>
                <bundle>true</bundle>
                <fragments>
                    <fragment>
                        <name>icons-fragment</name>
                        <files>
                            <file>bower_components/vaadin-icons/vaadin-icons.html</file>
                        </files>
                    </fragment>
                    <fragment>
                        <name>important-components</name>
                        <files>
                            <file>bower_components/vaadin-form-layout/vaadin-form-layout.html</file>
                            <file>bower_components/vaadin-form-layout/vaadin-form-item.html</file>
                            <file>bower_components/vaadin-text-field/vaadin-text-field.html</file>
                            <file>bower_components/vaadin-text-field/vaadin-password-field.html</file>
                            <file>bower_components/vaadin-combo-box/vaadin-combo-box.html</file>
                        </files>
                    </fragment>
                    <fragment>
                        <name>grid-fragment</name>
                        <files>
                            <file>gridConnector.js</file>
                            <file>vaadin-grid-flow-selection-column.html</file>
                            <file>bower_components/vaadin-grid/vaadin-grid.html</file>
                            <file>bower_components/vaadin-grid/vaadin-grid-column-group.html</file>
                            <file>bower_components/vaadin-grid/vaadin-grid-sorter.html</file>
                        </files>
                    </fragment>
                </fragments>
            </configuration>
        </execution>
    </executions>
</plugin>

Defining Fragments with a configuration file

Same result may be achieved with a custom configuration file instead. Fragments are configured by adding a fragments object to your bundle configuration file. The fragments object should be an array of objects, where each object defines a fragment name and files that belong to the fragment.

fragments.json

{
  "fragments": [
    {
      "name": "icons-fragment",
      "files": ["bower_components/vaadin-icons/vaadin-icons.html"]
    },
    {
      "name": "important-components",
      "files": [
         "bower_components/vaadin-form-layout/vaadin-form-layout.html",
         "bower_components/vaadin-form-layout/vaadin-form-item.html",
         "bower_components/vaadin-text-field/vaadin-text-field.html",
         "bower_components/vaadin-text-field/vaadin-password-field.html",
         "bower_components/vaadin-combo-box/vaadin-combo-box.html"
       ]
    },
    {
      "name": "grid-fragment",
      "files": [
         "gridConnector.js",
         "vaadin-grid-flow-selection-column.html",
         "bower_components/vaadin-grid/vaadin-grid.html",
         "bower_components/vaadin-grid/vaadin-grid-column-group.html",
         "bower_components/vaadin-grid/vaadin-grid-sorter.html"
       ]
    }
  ]
}

You still have to configure Maven plugin if the json file is not in the default path (see corresponding parameter description for details):

pom.xml

<plugin>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-maven-plugin</artifactId>
    <version>${vaadin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>package-for-production</goal>
            </goals>
            <configuration>
                <bundle>true</bundle>
                <bundleConfiguration>${path.to.json.file.declared.above}</bundleConfiguration>
            </configuration>
        </execution>
    </executions>
</plugin>