frontend Documentation

1. Project Overview & Quickstart (home-assistant/frontend) Copy Chapter

File: README.md Copy Chapter

Home Assistant Frontend

This is the repository for the official Home Assistant frontend.

• View demo of Home Assistant
• More information about Home Assistant
• Frontend development instructions

Development Copy Chapter

• Initial setup: script/setup
• Development: Instructions
• Production build: yarn build
• Gallery: cd gallery && script/develop_gallery

Frontend development Copy Chapter

Classic environment Copy Section

A complete guide can be found at the following link. It describes a short guide for the build of project.

License Copy Chapter

Home Assistant is open-source and Apache 2 licensed. Feel free to browse the repository, learn and reuse parts in your own projects.

We use BrowserStack to test Home Assistant on a large variety of devices.

File: build-scripts/README.md Copy Chapter

Bundling Home Assistant Frontend

The Home Assistant build pipeline contains various steps to prepare a build.

• Generating icon files to be included
• Generating translation files to be included
• Converting TypeScript, CSS and JSON files to JavaScript
• Bundling
• Minifying the files
• Generating the HTML entrypoint files
• Generating the service worker
• Compressing the files

Converting files Copy Chapter

Currently in Home Assistant we use a bundler to convert TypeScript, CSS and JSON files to JavaScript files that the browser understands.

We currently rely on Webpack. Both of these programs bundle the converted files in both production and development.

For development, bundling is optional. We just want to get the right files in the browser.

Responsibilities of the converter during development:

• Convert TypeScript to JavaScript
• Convert CSS to JavaScript that sets the content as the default export
• Convert JSON to JavaScript that sets the content as the default export
• Make sure import, dynamic import and web worker references work
  • Add extensions where missing
  • Resolve absolute package imports
• Filter out specific imports/packages
• Replace constants with values

In production, the following responsibilities are added:

• Minify HTML
• Bundle multiple imports so that the browser can fetch less files
• Generate a second version that is ES5 compatible

Configuration for all these steps are specified in bundle.js.

File: cast/README.md Copy Chapter

Home Assistant Cast

Home Assistant Cast is made up of two separate applications:

• Chromecast receiver application that can connect to Home Assistant and display relevant information.
• Launcher website that allows users to authorize with their Home Assistant installation and launch the receiver app on their Chromecast.

Development Copy Chapter

• Run script/develop_cast to launch the Cast receiver dev server. Keep this running.
• Navigate to http://localhost:8080 to start the launcher
• Debug the receiver running on the Chromecast via chrome://inspect/#devices

Setting up development environment Copy Chapter

Registering development cast app Copy Section

• Go to https://cast.google.com/publish and enroll your account for the Google Cast SDK (costs $5)
• Register your Chromecast as a testing device by entering the serial
• Add new application -> Custom Receiver
  • Name: Home Assistant Dev
  • Receiver Application URL: http://IP-OF-DEV-MACHINE:8080/receiver.html
  • Guest Mode: off
  • Google Case for Audio: off

Setting dev variables Copy Section

Open src/cast/dev_const.ts and change CAST_DEV_APP_ID to the ID of the app you just created. And set the CAST_DEV_HASS_URL to the url of your development machine.

Changing configuration Copy Section

In configuration.yaml, configure CORS for the HTTP integration:

http:
  cors_allowed_origins:
    - https://cast.home-assistant.io
    - http://IP-OF-DEV-MACHINE:8080

Running development Copy Chapter

cd cast
script/develop_cast

The launcher application will be accessible at http://localhost:8080 and the receiver application will be accessible at http://localhost:8080/receiver.html (but only works if accessed by a Chromecast).

Developing cast widgets in HA ui Copy Section

If your work involves interaction with the Cast parts from the normal Home Assistant UI, you will need to have that development script running too (script/develop).

Developing the cast demo Copy Section

The cast demo is triggered from the Home Assistant demo. To work on that, you will also need to run the development script for the demo (script/develop_demo).

File: gallery/public/images/brand/README.md Copy Chapter

Note!

Note, the assets in this folder, are not part of the CC license this repository is shipped in.
All rights reserved.

File: landing-page/README.md Copy Chapter

Home Assistant OS Landingpage

On initial startup of Home Assistant, HAOS needs to download Home Assistant core before the setup can start.
In this time the home-assistant/landingpage is serving a "Preparing Home Assistant" page.

Functionality Copy Chapter

• Progress bar to show download
• Show / hide supervisor logs
• Links
  • Read our Vision
  • Join our community
  • Download our app
• DNS issue handler
  • if the supervisor is not able to connect to the internet
  • Show actions to set dns to google or cloudflare to resolve the issue
• Error handler
  • if something with the installation goes wrong, we show the logs

Develop Copy Chapter

It is similar to the core frontend dev.

• frontend repo is building stuff
• landingpage repo can set the frontend repo path and serve the dev frontend

landingpage dev server Copy Section

• clone home-assistant/landingpage
• Add frontend repo as mount to your devcontainer config
  • please do not commit this changes, you can remove it after initial dev container build, because the build will keep the options as long as you don't rebuild it.
  • "mounts": ["source=/path/to/hass/frontend,target=/workspaces/frontend,type=bind,consistency=cached"]
• use the dev container
• start the dev server with following optional env vars:
  • SUPERVISOR_HOST to have real supervisor data, you can setup a supervisor remote API access and set the host of your supervisor. e.g.: SUPERVISOR_HOST=192.168.0.20:8888
  • SUPERVISOR_TOKEN the supervisor api token you get from the Remote API proxy Addon Logs
  • FRONTEND_PATH the path inside your container should be /workspaces/frontend
  • example: SUPERVISOR_TOKEN=abc123 SUPERVISOR_HOST=192.168.0.20:8888 FRONTEND_PATH=/workspaces/frontend go run main.go http.go mdns.go
  • You can also add this into your devcontainer settings, but then it's not so flexible to change if you want to test something else.

frontend dev server Copy Section

• install all dependencies
• run landing-page/script/develop

2. Official Technical Reference & Guides (home-assistant/home-assistant.github.io) Copy Chapter

Home Assistant website

This is the source for the Home-Assistant.io website.

Access Copy Chapter

You can access the site at the following URLs, depending on the target branch:

• Production (current branch): https://www.home-assistant.io
• Beta (rc branch): https://rc.home-assistant.io
• Development (next branch): https://next.home-assistant.io

Additionally, Netlify provides a preview deployment for every pull request, linked in the first PR comment.

Setup Copy Chapter

Setting up to contribute to documentation and the process for submitting pull requests is explained in the developer documentation.

Site preview Copy Chapter

In order to make the preview available on http://127.0.0.1:4000, use the following bundler command:

bundle exec rake preview

If the preview is not running on your local machine, pass the IP of the target machine from where it should be served as a parameter, i.e. to access on http://192.168.0.123:4000:

bundle exec rake preview[192.168.0.123]

Speeding up site generation Copy Chapter

Every release we post long changelogs to the website. This slows down generation of the website significantly! We include some tools to temporarily exclude the blog posts that you're not working on out of the way.

bundle exec rake isolate[filename-of-blogpost]

When you're done working on the site, run the following command to move the posts back again:

bundle exec rake integrate