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

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Documented new frontend development script #2483

Changes from 2 commits
Commits
Show all changes
3 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
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
```

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
```
Comment on lines +76 to +84
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 refers to a non-existent script

The documentation refers to a script/develop_and_serve script and its -c option, but this script does not exist in the codebase. The development server is actually managed through npm scripts defined in package.json, which uses Docusaurus commands and doesn't support the documented URL configuration option.

  • Remove or update the documentation at docs/frontend/development.md to reflect the correct development server setup using npm start or the appropriate Docusaurus commands
  • Remove the incorrect information about the -c option for changing the Home Assistant URL
🔗 Analysis chain

Verify documentation against the frontend implementation

Let's verify that the documented command and options match the implementation in PR #23062.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Verify the script implementation matches the documentation

# Check if the script exists and verify its contents
if [ -f "script/develop_and_serve" ]; then
    echo "Checking script/develop_and_serve implementation..."
    cat script/develop_and_serve
else
    echo "Warning: script/develop_and_serve not found"
fi

# Search for related test files
fd -t f -e ts -e js "develop.*serve" test/

Length of output: 272

Script:

#!/bin/bash
# Let's check if the script exists in a different location and search for related files
fd -t f "develop_and_serve"

# Search for any files containing references to the script or its options
rg -i "develop_and_serve"

# Search for any configuration or URL-related patterns in the frontend code
rg -i "hass_url|hassUrl|HASS_URL" src/

Length of output: 299

Script:

#!/bin/bash
# Let's check the dev scripts directory and package.json for development commands
fd -t f "package.json"

# Check the content of package.json for development scripts
cat package.json

# Look for any development server or configuration related files
fd -t f -e js -e ts "dev-server|webpack.config"

Length of output: 1140

🧰 Tools
🪛 LanguageTool

[misspelling] ~67-~67: The verb or noun ‘bypass’ is spelled as one word.
Context: ... Assistant url the frontend connects to by passing the -c option. This will also work for ...

(BY_PASS)

[misspelling] ~67-~67: Did you mean the verb “log out” instead of the noun ‘logout’?
Context: ... value for this option you will need to logout from your development frontend before i...

(LOG_IN)


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