Your first frontend contribution

The quickest way into the frontend is a small, visible fix: a misaligned icon, a label that is cut off, a button that does nothing on mobile. You see the result in your browser the moment you save, and a reviewer can judge it from a screenshot.

1. Find something to work on

Browse the good first issue label in the frontend repository, or the open bugs. A bug you ran into yourself is a great first topic, because you already know how to reproduce it.

Leave a comment that you are working on it, so nobody else picks it up at the same time.

Tip

Want to build a new card instead? That does not need any of the steps below. Start with Custom cards and more, and publish it in the Marketplace: that is where the project recommends a new card starts.

2. Set up the environment

The easiest setup is Visual Studio Code with the devcontainer of the frontend repository. It installs the right Node.js and pnpm for you.

Fork the frontend repository on GitHub.
Clone your fork and open it in Visual Studio Code.
When Visual Studio Code asks, select Reopen in Container. The first start takes a few minutes while the dependencies install.

Prefer to work without a container? Set up the environment covers both.

3. Run it

You need a Home Assistant instance to talk to. Inside the devcontainer you can run one next to the frontend:

Open a terminal and start Home Assistant Core. The first run installs the dev branch of Core and creates a configuration with demo entities:
Shell
```
script/core
```
Open a second terminal and start the frontend development server:
Shell
```
pnpm dev
```
Wait for Build done, then open http://localhost:8124 on your computer and create a user.

Already have a Home Assistant at home? You can also point the development frontend at that. Run the frontend explains both ways.

4. Make your change

Create a branch, make your change, and save. The development server rebuilds, and a refresh of the browser shows the result.

A few things reviewers look for, even in a small fix:

All text people see comes from src/translations/en.json, never hardcoded in the code.
Use the existing ha-* components and theme variables, not new colors or one-off controls.
Check your change on a narrow screen, and in the dark theme.

The coding guidelines have the details.

5. Check your work

Run the linters and the unit tests before you push:

Shell

pnpm lint
pnpm test

A pre-commit hook already formats the files you commit, so most style issues fix themselves.

6. Open a pull request

Push your branch to your fork and open a pull request against the dev branch. Fill in the pull request template completely: describe the change from the point of view of the people using it, check exactly one Type of change, and add before and after screenshots for anything visual. A check fails the pull request when the template is missing or incomplete.

Then expect questions. Reviewers may ask you to change things, and that is normal. Review and release explains what happens next.

What is next

Read the architecture overview to see how the pieces fit together.
Look at the components before you build something new. Reusing an existing one is almost always better.
Help review: test someone else's pull request and leave your findings. It speeds things up for everyone, yours included.