diff --git a/docs/frontend/development.md b/docs/frontend/development.md deleted file mode 100644 index 0ae9e0cf344..00000000000 --- a/docs/frontend/development.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: "Frontend development" -sidebar_label: "Development" ---- - -The Home Assistant frontend is built using web components. For more background about our technology choices, [see this blog post](https://developers.home-assistant.io/blog/2019/05/22/internet-of-things-and-the-modern-web.html). - -:::caution -Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes. -::: - -## Setting up the environment - -### Getting the code - -The first step is to fork the [frontend repository][hass-frontend] and add the upstream remote. You can place the forked repository anywhere on your system. - -```shell -git clone git@github.com:YOUR_GIT_USERNAME/frontend.git -cd frontend -git remote add upstream https://github.com/home-assistant/frontend.git -``` - -### Configuring Home Assistant - -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: - -```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`: - -```json -"mounts": [ - "source=/path/to/hass/frontend,target=/workspaces/frontend,type=bind,consistency=cached" -] -``` - -The Home Assistant's devcontainer needs to get rebuilt via the `docker-build` [task](/development_environment.mdx#tasks), and the `configuration.yaml` should point to the path inside the container: - -```yaml -frontend: - development_repo: /workspaces/frontend/ -``` - -The change to `.devcontainer/devcontainer.json` should be excluded from any PR as it contains your local path to the `frontend` repository. - -### Installing Node.js - -Node.js is required to build the frontend. The preferred method of installing node.js is with [nvm](https://github.com/creationix/nvm). Install nvm using the instructions in the [README](https://github.com/creationix/nvm#install-script), and install the correct node.js by running the following command: - -```shell -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/en/docs/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: - -```shell -nvm use -script/bootstrap -``` - -## 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: - -```shell -nvm use -script/develop -``` - -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` - -

- -

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

- -

- -## Creating pull requests - -If you're planning on issuing a PR back to the Home Assistant codebase you need to fork the frontend project and add your fork as a remote to the Home Assistant frontend repo. - -```shell -git remote add fork -``` - -When you've made your changes and are ready to push them change to the working directory for the frontend project and then push your changes - -```bash -git add -A -git commit -m "Added new feature X" -git push -u fork HEAD -``` - -## Building the frontend - -If you're making changes to the way the frontend is packaged, it might be necessary to try out a new packaged build of the frontend in the main repository (instead of pointing it at the frontend repo). To do so, first build a production version of the frontend by running `script/build_frontend`. - -To test it out inside Home Assistant, run the following command from the main Home Assistant repository: - -```shell -pip3 install -e /path/to/hass/frontend/ -hass --skip-pip-packages home-assistant-frontend -``` - -[hass-frontend]: https://github.com/home-assistant/frontend diff --git a/docs/frontend/development.mdx b/docs/frontend/development.mdx new file mode 100644 index 00000000000..82e7e923084 --- /dev/null +++ b/docs/frontend/development.mdx @@ -0,0 +1,156 @@ +--- +title: "Frontend development" +sidebar_label: "Development" +--- + +```mdx-code-block +import {useState} from 'react'; + +export const RepositoryOpener = () => { + const [value, setValue] = useState(0); + const repoUrl = `vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=${encodeURIComponent(value)}`; + return
+ setValue(ev.target.value)} style={{width: "80%", display: "inline-block", marginRight: 16}} /> + +
+} +``` + +The Home Assistant frontend is built using web components. For more background about our technology choices, [see this blog post](https://developers.home-assistant.io/blog/2019/05/22/internet-of-things-and-the-modern-web.html). + +:::caution +Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes. +::: + +## Setup with Visual Studio Code + devcontainer + +The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/remote/containers) + +**Prerequisites** + +- [Docker](https://docs.docker.com/get-docker/) +- [Visual Studio code](https://code.visualstudio.com/) +- [Git](https://git-scm.com/) + +**Getting started:** + +1. Go to [Home Assistant frontend repository][hass-frontend] and click "fork". +2. Once your fork is created, copy the URL of your fork and paste it below, then click "Open": + +3. Your browser will prompt you if you want to use Visual Studio Code to open the link, click "Open Link". +4. When Visual Studio Code asks if you want to install the Remote extension, click "Install". +5. The Dev Container image will then be built (this may take a few minutes), after this your development environment will be ready. + + In the future, if you want to get back to your development environment: open Visual Studio Code, click on the "Remote Explorer" button in the sidebar, select "Containers" at the top of the sidebar. + +**Configuring Home Assistant** + +1. Follow the [instructions for setting up a Home Assistant devcontainer](/development_environment.mdx#developing-with-visual-studio-code--devcontainer) +2. Mount the `frontend` directory into the Core devcontainer by adding the following section to `.devcontainer/devcontainer.json` file in the `core` repository. + + ```json + "mounts": [ + "source=/path/to/hass/frontend,target=/workspaces/frontend,type=bind,consistency=cached" + ] + ``` + + *Make sure that you exclude the change to `.devcontainer/devcontainer.json` from any PRs as it points to local `frontend` repository path.* +3. Rebuild the Core devcontainer by running the `Dev Containers: Rebuild Container` command in Visual Studio Code to pickup the new `mounts` configuration if you used it before making the change. +4. Update the Home Assistant configuration to point to the mounted `frontend` path. + + ```yaml + frontend: + development_repo: /workspaces/frontend/ + ``` + +## Setup Manually + +**Getting Started:** + +1. Fork and clone the [Home Assistant frontend repository][hass-frontend]. +2. Install Node.js + + The preferred method is using [nvm](https://github.com/creationix/nvm). Follow the [nvm installation instructions](https://github.com/creationix/nvm#install-script) and then use it to install Node.js by runnig + + ```shell + nvm install + nvm use + ``` + + This installs the version of Node.js defined in the `.nvmrc` file and then sets it as the current active version. + + If you're running on Windows, you will need to use an alternative version of nvm like [nvm-windows](https://github.com/coreybutler/nvm-windows). This version of nvm doesn't automatically pickup `.nvmrc` so you'll need to manually select the correct version. +3. Install [Yarn](https://yarnpkg.com/en/), the package manager used by the frontend, using the [installation instructions](https://yarnpkg.com/en/docs/install) +4. Install all of the development dependencies by running: + + ```shell + script/bootstrap + ``` + +**Configuring Home Assistant:** + +*These instructions assume that you are also [manually running Home Assistant](https://developers.home-assistant.io/docs/development_environment#manual-environment)* + +Update the `frontend` configuration section in your `configuration.yaml` to point to the path of the `frontend` repository you cloned + +```yaml +frontend: + # Example absolute path: /home/paulus/dev/hass/frontend + development_repo: /path/to/hass/frontend/ +``` + +## Development + +Whenever you make changes to files during development, you need to rebuild the development environment so that the Home Assistant instance will pickup the changes. The `script/develop` script will monitor and auto-update the build whenever anything changes. + +```shell +script/develop +``` + +Many files will be cached by your web browser so you should disable caching to avoid stale content: + +:::info +Instructions are for Google Chrome +::: + +1. Disable cache by ticking the box in `Network` > `Disable cache` + +

+ +

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

+ +

+ +## Creating pull requests + +If you're planning on issuing a PR back to the Home Assistant codebase you need to fork the frontend project and add your fork as a remote to the Home Assistant frontend repo. + +```shell +git remote add fork +``` + +When you've made your changes and are ready to push them change to the working directory for the frontend project and then push your changes + +```bash +git add -A +git commit -m "Added new feature X" +git push -u fork HEAD +``` + +## Building the frontend + +If you're making changes to the way the frontend is packaged, it might be necessary to try out a new packaged build of the frontend in the main repository (instead of pointing it at the frontend repo). To do so, first build a production version of the frontend by running `script/build_frontend`. + +To test it out inside Home Assistant, run the following command from the main Home Assistant repository: + +```shell +pip3 install -e /path/to/hass/frontend/ +hass --skip-pip-packages home-assistant-frontend +``` + +[hass-frontend]: https://github.com/home-assistant/frontend +[hass-core]: https://github.com/home-assistant/core diff --git a/docs/supervisor/development.md b/docs/supervisor/development.md index d8a030df193..78cd17bb119 100644 --- a/docs/supervisor/development.md +++ b/docs/supervisor/development.md @@ -84,7 +84,7 @@ Your local Home Assistant installation will now connect to a remote Home Assista ## Frontend development -The instructions here is for development of the Supervisor panel, we're going to assume that you have a [Home Assistant frontend development environment](/frontend/development.md) set up with the devcontainer, and that you have [Supervisor API Access](#supervisor-api-access) set up. +These instructions are for development of the Supervisor panel. They assume that you have a [Home Assistant frontend development environment](/frontend/development.mdx) set up with the devcontainer, and that you have [Supervisor API Access](#supervisor-api-access) set up. 1. Run the "Develop Supervisor panel" task 2. Run the task "Run HA Core for Supervisor in devcontainer"