Build System and Project Structure

The following tools are used in Polymer client build chain:

By default Gradle handles installation and invocation of these tools. It’s possible to use them directly, see Using Native Polymer Tools.

Polymer 2.x and its native elements are written using ES6, thus it requires an additional build step (ES6 → ES5 compilation) in order to support old browsers.

The default preset used in Polymer client is es6-unbundled. It means that if you are targeting old browsers and production deployment you should change it to es5-bundled.

In order to change build preset open polymer.json and change builds property accordingly e.g.:

  "builds": [
    {
      "preset": "es5-bundled",
      "basePath": "/app-front/",
      "addServiceWorker": false
    }
  ]

You can specify several presets or customize build process in polymer.json. More info about presets and options is available on Polymer website.

In order the results of specific preset build being deployed to Tomcat you need to change deploy task in build.gradle:

    task deploy(type: Copy, dependsOn: [assemble, deployUnbundled]) {
        from file('build/es5-unbundled')
        into "$cuba.tomcat.dir/webapps/$frontAppDir"
    }

Notice es6-bundled → es5-unbundled change in polymer.json and build.gradle.

Directory Structure

front/
|-- src/
|   |-- app-shell.html
|   |-- shared-styles.html
|-- images
|   |-- app-icon/
|   |-- favicon.ico
|-- .gitignore
|-- bower.json
|-- index.html
|-- manifest.json
|-- package.json
|-- polymer.json
|-- service-worker.js
|-- sw-precache-config.js

src: Folder where components are placed.
package.json: Lists dependencies on Node.js modules which will be used in a build purposes.
bower.json: Lists dependencies on web libraries (primarily web components) which will be used at runtime.
polymer.json: Polymer build configuration.
index.html: An application entry point. Contains logic on loading polyfills and <appname>-shell.html import.
manifest.json: Web app manifest. Contains information which used when the application is being added to a device’s home screen. More info: https://developer.mozilla.org/en-US/docs/Web/Manifest
service-worker.js: Service worker stub.
sw-precache-config.js: Config used by sw-precache library in order to generate service worker at build time (disabled by default). See Offline Capabilities.

Hot Deploy

When you run and deploy your application using CUBA Studio or Gradle the build system will bundle your components according to the configuration in polymer.json file. By default, it will bundle the whole application into a single app-shell.html file. When you change some of your app components Studio will hot deploy it to the tomcat. Also, it will replace bundled app-shell.html with an unbundled version in order changes to be picked. Keep it in mind if you deploy your application on production directly from tomcat/webapps.

If you use es5-bundled build preset, hot deploy will not work as expected since Studio does not perform any JavaScript transpilation on the fly.

If you use TypeScript based client you have to run npm run watch command manually to hot-deploy changes in components classes.

Using Native Polymer Tools

You can use native Polymer framework toolchain when developing Polymer UI components. It can be convenient if a separate team of front-end developers works on the project. In this case, Node.js should be installed on the system.

Install bower and polymer-cli globally:

npm install bower polymer-cli -g

Then you can build and run the web application without Gradle:

cd modules/front
npm install
bower install
polymer serve

You need to specify the absolute path to REST API in modules/front/index.html if you want to serve the app by polymer server (instead of Tomcat), e.g.:

<myapp-shell api-url="http://localhost:8080/app/rest/"></myapp-shell>

After that, the web application will be available at http://localhost:8081 (see the particular port in command line output) and it will work with the REST API running at http://localhost:8080/app/rest/.