Advanced production mode topics

Production mode issues

After adding the flow-server-production-mode dependency the application no longer starts.

This is a problem when you run the application in development mode using maven jetty:run, but due to the production mode dependency the application tries to get the resources from the production mode folder.

To fix this you have a couple choices:

  • Use the defined profile from Basic production mode, with the jetty plugin.

  • running the application with mvn jetty:run-exploded or mvn jetty:run-war

  • disable production mode using the servlet parameter original.frontend.resources=true

  • compile the frontend resources by adding the vaadin-maven-plugin see: Basic production mode

  • remove the flow-server-production-mode dependency

Plugin goals and goal parameters

Here we describe the maven plugin goals and their usage.

copy-production-files

The intention of the goal is to provide jar resources support by copying all files required for Flow production mode from them and application’s frontend directory. If no jars with the dependencies to be copied are present in the project’s dependencies, this goal can be omitted or replaced with more simple plugins to copy files from application’s frontend directory.

After the goal is complete, the web files required by an application to work properly are copied into the copyOutputDirectory. Files are copied from:

  • WebJars that are in the project’s dependencies: all directories in any WebJar that contain bower.json will be copied to the output.

  • regular jars, all files from META-INF/resources/frontend directories inside of a jar, if present

  • frontendWorkingDirectory

All files are filtered so that no file is copied if it matches any glob pattern from excludes.

Goal parameters

  • copyOutputDirectory default: ${project.build.directory}/frontend/

    1. The directory to copy files to.

  • excludes default: **/LICENSE*,**/LICENCE*,**/demo/**,**/docs/**,**/test*/**,**/.*,**/*.md,**/bower.json,**/package.json,**/package-lock.json

    1. File globs to specify files that should not be copied to copyOutputDirectory, set in regular Maven fashion: single string, comma-separated values.

  • frontendWorkingDirectory default: ${project.basedir}/src/main/webapp/frontend/

    1. Can also be set with `frontend.working.directory` Maven property.
    2. The application's directory to copy files from.

package-for-production

The intention of the goal is to process application web files in order to optimize them for production usage: minify them, transpile to ES5 and bundle them (squash all frontend files into bigger files to reduce the amount of server round-trips). In order to process the files, special frontend tools are downloaded. The tools are: node, yarn, gulp and a set of libraries required by gulp that are installed with yarn. If any error occurs during the actual processing, it is logged, but the processing does not stop. The goal produces two sets of files:

  • ES6 set, for modern browsers

  • ES5 set, for old browsers that do not support ES6 (optional, can be turned off if not needed)

Both sets are used by Flow depending on the browser type.

Goal parameters

  • transpileEs6SourceDirectory default: ${project.build.directory}/frontend/

    1. The directory with application's web files to be processed, by default it's the same as `copyOutputDirectory` from the `copy-production-files` goal.
    2. All js, html and css files in the directory will be processed before the goal finishes except for `webcomponentsjs` directory, if present.
    3. This directory contains special libraries required for the ES5 WebComponents to work and should not be touched.

  • transpileWorkingDirectory default: ${project.build.directory}/

    1. The directory to download all frontend tools to.

  • transpileOutputDirectory default: ${project.build.directory}/${project.build.finalName}/

    1. The directory to put produced sets of files into.

  • es6OutputDirectoryName default: frontend-es6

    1. The name of the directory with ES6 file set, will be created in `transpileOutputDirectory`.

  • es5OutputDirectoryName default: frontend-es5

    1. The name of the directory with ES5 file set, will be created in `transpileOutputDirectory`.

  • skipEs5 default: false

    1. ES5 transpilation can be turned off with this parameter, in this case no `es5OutputDirectoryName` will be present.

  • bundle default: true

    1. Collect all project frontend dependencies into a single file, bundle. Works both for es6 and es5 (if enabled).

  • fragments default: null

    1. Optional way to split the project frontend dependencies' bundle into multiple fragments.
    2. Will be used only if bundling is enabled. See [Bundle Configuration](#bundle-configuration) section for details.

  • bundleConfiguration default: ${project.basedir}/bundle-configuration.json

    1. Optional path to a json file containing additional configuration parameters used when bundling dependencies.
    2. The file will only be used if bundling is enabled and the file exists.
    3. The possible configurations this file can contain are documented below in the [Bundle Configuration](#bundle-configuration) section.

  • nodeVersion default: v8.9.0

    1. If any different `node` version should be used, it can be specified here.

  • yarnVersion default: v1.3.2

    1. If any different `yarn` version should be used, it can be specified here.

  • ignoreMavenProxies default: true

    1. Turn it on to download all frontend tools using Maven proxy configurations.

  • minify default: true

    1. Turn it on to minify ES5 and ES6 code.

  • hash default: true

    1. Turn it on to make bundle receive a hash for the content. This
    2. makes the bundle update on content change after it is cached in
    3. the browser.

  • yarnNetworkConcurrency default: -1

    1. Set the maximum number of concurrent network requests. By default there is no any limit.

After the goal is complete, the files from transpileEs6SourceDirectory are processed. It results in:

  • transpileOutputDirectory/es6OutputDirectoryName with all files from transpileEs6SourceDirectory copied into it and with all *.css, *.js and *.html additionally optimized for production usage.

  • If not configured to be skipped, transpileOutputDirectory/es5OutputDirectoryName with all files from transpileEs6SourceDirectory copied into it and with all *.css, *.js and *.html additionally optimized for production usage AND transpiled into ES5 so that old browsers are able to use the application still

  • transpileWorkingDirectory with all frontend tools and additional files created for the tools, can be ignored after the process