Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documented new frontend development script #2483

Merged
merged 6 commits into from
Jan 22, 2025
Merged

Documented new frontend development script #2483

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ee25cac
Documented new feature added in pull request 23062
martetassyns Dec 2, 2024
9d93755
applied review comment to use tabs instead
martetassyns Dec 6, 2024
07e41cd
applied review comment
martetassyns Dec 12, 2024
28f2021
Merge branch 'master' into feat/document-PR-23062
MindFreeze Jan 22, 2025
9bad6d6
capitalize Frontend
MindFreeze Jan 22, 2025
6dc7c74
add a section about develop_and_serve
MindFreeze Jan 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion docs/frontend/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,15 @@ 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:
There are two ways to test the frontend. You either configure Home Assistant to use another frontend. Or you configure the frontend to connect to an existing Home Assistant instance. The first option is how it will work in production. The second allows running a development frontend against an existing Home Assistant without modifying it. However the downside is that not everything can be tested this way. For example, the login page will always be the one built-in into your Home Assistant.

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

<Tabs>

<TabItem value="frontend inside Home Assistant">
To configure Home Assistant to use the development mode for the frontend, update the frontend config in your `configuration.yaml` and set the path to the frontend repository that you cloned in the last step:

```yaml
frontend:
Expand All @@ -51,6 +59,32 @@ 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.
:::
</TabItem>

<TabItem value="frontend outside Home Assistant">

If you setup your frontend development environment so that you can run the `script/develop` script as described in section [Development](#development). You can use the following command as a replacement to develop and run the frontend on http://localhost:8124 and it will connect to the Home Assistant running on http://localhost:8123. Note that if you are running this command from a devcontainer, the url should be accessed from the container host.

```shell
script/develop_and_serve
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Documentation references non-existent script

The documentation refers to script/develop_and_serve multiple times, but this script does not exist in the repository. The documentation needs to be corrected to reference the actual development script that should be used, or the referenced script needs to be implemented.

  • docs/frontend/development.md: Multiple references to non-existent script/develop_and_serve
    • Line 101: Basic usage
    • Line 164: Usage with custom connection URL
🔗 Analysis chain

Verify script implementation.

The documentation refers to script/develop_and_serve. Please ensure this script is properly implemented in the frontend repository (PR #23062) before merging this documentation.

Also applies to: 164-164

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Verify the script exists in the frontend repository
# Note: This assumes we're in the frontend repository from PR #23062

if [ -f "script/develop_and_serve" ]; then
    echo "Script exists. Checking implementation..."
    cat script/develop_and_serve
else
    echo "Warning: script/develop_and_serve not found"
fi

Length of output: 134

Script:

#!/bin/bash
# Search for similarly named files
echo "=== Searching for similarly named files ==="
fd -t f "develop.*serve" || true

echo -e "\n=== Searching for references to the script ==="
rg -i "develop.*serve" || true

Length of output: 2139

```

You can change the Home Assistant url the frontend connects to by passing the -c option. This will also work for existing production core instances. It does not need to be a development version hosted locally. However, if you change the value for this option you will need to logout from your development frontend before it actually switches to the new value. For example:

```shell
script/develop_and_serve -c https://myhost.duckdns.org:8123
```
MindFreeze marked this conversation as resolved.
Show resolved Hide resolved

You can change the port the frontend is served on by passing the -p option. Note that if you are running from a devcontainer, you will need to setup
port forwarding as well if you want to access it from the container host. For example:

```shell
script/develop_and_serve -p 8654
```

</TabItem>

</Tabs>

### Installing Node.js

Expand Down