Home Assistant

Frontend Development

Home Assistant uses Polymer for the UI and NuclearJS for maintaing the app state.

Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.

Setting up the environment

Home Assistant will by default serve the compiled version of the frontend. To enable development mode for Home Assistant, update your configuration.yaml to have these lines:

http:
  development: 1

Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You can setup the frontend development environment by running:

$ script/setup

Development

While you are developing, you need to have webpack running to have your JavaScript changes be made available.

$ cd homeassistant/components/frontend/www_static/home-assistant-polymer
$ npm run js_dev

The source code for the frontend can be found in two different directories:

  • UI: homeassistant/components/frontend/www_static/home-assistant-polymer/src/
  • Core: homeassistant/components/frontend/www_static/home-assistant-polymer/node_modules/home-assistant-js/src/

After your changes have been accepted into the home-assistant-js repository, you’ll have to update Home Assistant Polymer to use the latest version of it. This can be done by updating package.json. Look for the line that contains home-assistant-js and update the SHA to the SHA of the last commit.

Building the Polymer frontend

Building a new version of the frontend is as simple as running script/build_frontend. This fires off the following commands:

  • home-assistant-polymer: Install NPM dependencies.
  • home-assistant-polymer: start frontend build.
    • Compile all used JavaScript to _app_compiled.js.
    • Install Bower dependencies.
    • Vulcanize all Webcomponents to frontend.vulcan.html.
    • Minify frontend.vulcan.html and save it as frontend.html.
  • Copy the webcomponents polyfill webcomponents-lite.min.js from home-assistant-polymer to components/frontend/www_static/webcomponents-lite.min.js.
  • Copy the final frontend build frontend.html from home-assistant-polymer to components/frontend/www_static/frontend/.
  • Generate MD5 hash of frontend.html to signal caches to redownload the UI.

Polymer build architecture diagram Polymer build architecture diagram