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
+43 −1
Open

Documented new frontend development script #2483

Changes from all 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
44 changes: 43 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 with minimal interference. 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,40 @@ 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 want to connect your development frontend to an existing home assistant instance without replacing the UI completely, you will need to add the url under which your development frontend is hosted in `configuration.yaml` of the home assistant it will be connecting to.

```yaml
http:
cors_allowed_origins:
- http://localhost:8124
```

After you've 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
```
Comment on lines +74 to +91
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 in docs/frontend/development.md refers to a script/develop_and_serve script that does not exist in the repository. The repository is actually a Docusaurus-based documentation site with different development commands:

  • The actual development server is started using npm run start:development or npm run start:devcontainer
  • The documented functionality about connecting to Home Assistant and port configuration is not present in the codebase
🔗 Analysis chain

Verify the development server implementation

Let's verify how the development server is actually implemented to ensure the documentation matches reality.

Let's gather more information by checking the actual script content and related files.

Let's check the docusaurus configuration and look for any development-related scripts in the root directory, as the script might be in a different location.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Description: Check the actual implementation of the development server

# Look for development server related files and scripts
echo "Checking for development server scripts..."
fd -t f "develop.*serve|dev-server" 

# Check package.json for development scripts
echo "Checking package.json for development scripts..."
if [ -f "package.json" ]; then
    jq '.scripts | with_entries(select(.key | contains("develop")))' package.json
fi

# Look for webpack configurations
echo "Checking for webpack configurations..."
fd -t f "webpack.*config"

Length of output: 506

Script:

#!/bin/bash
# Check the content of the script/develop_and_serve
echo "Checking script/develop_and_serve content..."
cat script/develop_and_serve

# Look for any related development scripts
echo -e "\nChecking other development scripts..."
fd -t f "^develop" script/

# Check if there are any related configuration files
echo -e "\nChecking for configuration files..."
fd -t f "config|\.rc" -d 1

# Check docusaurus configuration since we saw docusaurus in package.json
echo -e "\nChecking docusaurus configuration..."
fd -t f "docusaurus\.config\.js"

Length of output: 588

Script:

#!/bin/bash
# Check docusaurus configuration content
echo "Checking docusaurus.config.js content..."
cat docusaurus.config.js

# Look for development scripts in the root directory
echo -e "\nChecking for development scripts in root..."
fd -t f "develop.*serve|develop" .

# Check if there are any npm/yarn scripts in package.json
echo -e "\nChecking complete package.json..."
cat package.json

Length of output: 6257

🧰 Tools
🪛 LanguageTool

[style] ~74-~74: In American English, “you” and “have” do not usually form a contraction unless they’re followed by a past participle.
Context: ... - http://localhost:8124 ``` After you've setup your frontend development environ...

(IVE_I_HAVE_AMERICAN_STYLE)

[uncategorized] ~74-~74: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...un the frontend on http://localhost:8124 and it will connect to the Home Assistant r...

(COMMA_COMPOUND_SENTENCE)

[misspelling] ~80-~80: 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)

[uncategorized] ~80-~80: Possible missing comma found.
Context: ...wever, if you change the value for this option you will need to logout from your devel...

(AI_HYDRA_LEO_MISSING_COMMA)

[misspelling] ~80-~80: 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)

[grammar] ~86-~86: The word “setup” is a noun. The verb is spelled with a space.
Context: ...g from a devcontainer, you will need to setup port forwarding as well if you want to ...

(NOUN_VERB_CONFUSION)

🪛 Markdownlint (0.37.0)

74-74: null
Bare URL used

(MD034, no-bare-urls)

74-74: null
Bare URL used

(MD034, no-bare-urls)


</TabItem>

</Tabs>

### Installing Node.js

Expand Down