mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-13 12:26:29 +00:00
Clarify frontend development documentation (#2497)
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
William Poetra Yoga
GitHub
parent
2d96523d78
commit
af4abd1094
@ -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**
|
||||
|
||||
<p class='img'>
|
||||
<img src='/img/en/development/disable-cache.png' />
|
||||
</p>
|
||||
|
||||
2. Enable Bypass for network in `Application` > `Service Workers` > `Bypass for network`
|
||||
2. Enable Bypass for network in **Application** > **Service Workers** > **Bypass for network**
|
||||
|
||||
<p class='img'>
|
||||
<img src='/img/en/development/bypass-for-network.png' />
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user