From af4abd1094ef80e504c5b98f64decae050b3b050 Mon Sep 17 00:00:00 2001 From: William Poetra Yoga Date: Mon, 16 Dec 2024 03:45:19 +0700 Subject: [PATCH] Clarify frontend development documentation (#2497) Co-authored-by: Franck Nijhof --- docs/frontend/development.md | 69 ++++++++++++++++++++++++++---------- 1 file changed, 51 insertions(+), 18 deletions(-) diff --git a/docs/frontend/development.md b/docs/frontend/development.md index 2f0dd764..f4d44ab5 100644 --- a/docs/frontend/development.md +++ b/docs/frontend/development.md @@ -25,15 +25,9 @@ git remote add upstream https://github.com/home-assistant/frontend.git You will need to have an instance of Home Assistant set up. See our guide on [setting up a development environment](/development_environment.mdx). -Next step is to configure Home Assistant to use the development mode for the frontend. Do this by updating the frontend config in your `configuration.yaml` and set the path to the frontend repository that you cloned in the last step: +#### Developing with Visual Studio Code + dev container -```yaml -frontend: - # Example absolute path: /home/paulus/dev/hass/frontend - development_repo: /path/to/hass/frontend/ -``` - -If you are using Visual Studio Code with devcontainers for Home Assistant, you need to mount the `frontend` directory into the container. Add the following section to `.devcontainer/devcontainer.json`: +If you are using Visual Studio Code with dev containers for Home Assistant Core, you need to mount the frontend repository into the dev container. Add the following section to `.devcontainer/devcontainer.json` in the Home Assistant Core repository: ```json "mounts": [ @@ -41,18 +35,45 @@ If you are using Visual Studio Code with devcontainers for Home Assistant, you n ] ``` -The Home Assistant's devcontainer needs to get rebuilt via the `Dev Containers: Rebuild Container` with: Shift+Command+P(Mac) / Ctrl+Shift+P (Windows/Linux). The `configuration.yaml` should point to the path inside the container: +Rebuild the dev container by pressing Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux) to open the Command Palette, then selecting the **Dev Containers: Rebuild Container** command. + +Edit `config/configuration.yaml` at the root of the Home Assistant Core repository to add this entry: ```yaml frontend: - development_repo: /workspaces/frontend/ + development_repo: /workspaces/frontend ``` -:::caution -The change to `.devcontainer/devcontainer.json` should be excluded from any PR as it contains your local path to the `frontend` repository. Since the the settings in `.devcontainer/devcontainer.json` are only processed during the container rebuild, you can safely roll back the change after the rebuild has completed. +:::note +This is the mounted path inside the dev container, see the `target` parameter above. If the `source` path is incorrect, the web frontend won't work. ::: -### Installing Node.js +Run Home Assistant Core from VS Code: +1. Open the Command Palette: + - Mac: `Shift+Command+P` + - Windows/Linux: `Ctrl+Shift+P` +2. Select **Tasks: Run Task** +3. Select **Run Home Assistant Core** + +:::caution +The change to `.devcontainer/devcontainer.json` should be excluded from any PR as it contains your local path to the `frontend` repository. Since the settings in `.devcontainer/devcontainer.json` are only processed during the container rebuild, you can safely roll back the change after the rebuild has completed. +::: + +#### Developing with a manual environment + +If you set up the development environment for Home Assistant Core manually, fill in the frontend repository path in `configuration.yaml`: + +```yaml +frontend: + # Example path: /home/paulus/dev/hass/frontend + development_repo: /path/to/hass/frontend +``` + +:::tip +The `configuration.yaml` file can be found in the `config` directory at the root of the Home Assistant Core repository. If the path is incorrect or otherwise inaccessible, the web frontend won't work. +::: + +### Installing Node.js (manual environment only) Node.js is required to build the frontend. The preferred method of installing node.js is with [nvm](https://github.com/nvm-sh/nvm). Install nvm using the instructions in the [README](https://github.com/nvm-sh/nvm#install--update-script), and install the correct node.js by running the following command: @@ -62,7 +83,9 @@ nvm install [Yarn](https://yarnpkg.com/en/) is used as the package manager for node modules. [Install yarn using the instructions here.](https://yarnpkg.com/getting-started/install) -Next, development dependencies need to be installed to bootstrap the frontend development environment. First activate the right Node version and then download all the dependencies: +### Install development dependencies and fetch latest translations + +Bootstrap the frontend development environment by installing development dependencies and downloading the latest translations. ```shell nvm use @@ -70,28 +93,38 @@ script/bootstrap script/setup_translations ``` +:::note +This needs to be done manually, even if you are using dev containers. Also, you will be asked to enter a code and authorize the script to fetch the latest translations. +::: + ## Development -During development, you will need to run the development script to maintain a development build of the frontend that auto updates when you change any of the source files. To run this server, run: +### Run development server + +Run this script to build the frontend and run a development server: ```shell nvm use script/develop ``` -Make sure you have cache disabled and correct settings to avoid stale content: +When the script has completed building the frontend, and Home Assistant Core has been set up correctly, the frontend will be accessible at `http://localhost:8123`. The server will automatically rebuild the frontend when you make changes to the source files. + +### Browser settings + +Open Google Chrome's Developer tools, and make sure you have cache disabled and correct settings to avoid stale content: :::info Instructions are for Google Chrome ::: -1. Disable cache by ticking the box in `Network` > `Disable cache` +1. Disable cache by ticking the box in **Network** > **Disable cache**

-2. Enable Bypass for network in `Application` > `Service Workers` > `Bypass for network` +2. Enable Bypass for network in **Application** > **Service Workers** > **Bypass for network**