HA Component Kit

The HAKIT ecosystem is designed to help you build dynamic Home Assistant dashboards using React. It consists of two primary packages:

• @hakit/core: Provides the core functionality to authenticate with Home Assistant using the official Home Assistant Web Socket package.
• @hakit/components: A collection of reusable React components specifically designed for creating custom Home Assistant dashboards.

HA Component Kit is a collection of React-based packages designed for building highly customizable, real-time, and reactive smart home dashboards on top of Home Assistant.

It provides three main capabilities:

1. Custom UI Development: Build bespoke dashboards using standard React patterns.
2. Prebuilt Components: Use ready-made UI elements from @hakit/components.
3. Home Assistant Integration: Communicate with Home Assistant via @hakit/core, which wraps the official Home Assistant WebSocket API to handle authentication, state management, and actions.

When using HassConnect, the hassToken prop is a convenient way to provide authentication, but it carries significant security risks in production environments.

Risks

• Public Exposure: The Home Assistant www directory is not protected by authentication. Any file in this directory (including your dashboard and the token itself) is accessible to anyone who knows the URL if remote access is enabled.

Best Practices

• Local Development: Use the hassToken for local development and for running npm run sync.
• Production: Omit the token in production builds. This forces users to log in via the standard Home Assistant authentication flow, ensuring that only authorized users can access your dashboard and your Home Assistant instance.

The fastest way to set up a new project is using the npm create hakit@latest command. This command runs a terminal wizard that automatically configures a development environment including:

• React
• TypeScript
• Vite
• Hakit core functionality

You can spin up a localized version of the dashboard server on your machine without connecting to Home Assistant. This is useful for rapid styling and UI updates.

Setup Steps:

1. Create an options.json file inside the server directory:

   {
     "html_file_path": "www/ha-dashboard/index.html",
     "spa_mode": true
   }

2. Ensure your local directory structure mimics the Home Assistant structure so the server can find your files:

   hakit
     server
       - options.json
     config
       - www
           - ha-dashboard
               - index.html

3. Install dependencies and start the dev server:

   npm i && npm run dev

Once running, the dashboard will be available at http://localhost:2022.

If you prefer to add Hakit to an existing React project, you can install the core logic and the component library via npm:

• @hakit/core: Provides authentication and core functionality to interact with Home Assistant.
• @hakit/components: Provides reusable UI components designed for Home Assistant dashboards.

npm install @hakit/core @hakit/components

To use the core functionality (authentication and React hooks) and the pre-built UI components, install both @hakit/core and @hakit/components.

Note on npm versions: This package uses peerDependencies. If you are using npm version 7 or above, these will be installed automatically. If you are using npm version 4-6, you must install peer dependencies manually.

npm i @hakit/core @hakit/components -D

The sync-user-types script generates types specific to a user's Home Assistant instance. This process involves linking the @hakit/core package to your test dashboard and running a watch script.

Important Note: When running in watch mode, types are not automatically re-generated on subsequent changes. You must kill the terminal and restart the process to see new changes reflected.

Use the sync-ha-types script to synchronize types defined in the Home Assistant repository. This ensures that the component kit stays up-to-date with changes in Home Assistant without manual management. If changes are detected in the Home Assistant repository, the autogenerated-types-by-domain.ts file will be updated.

To extend or modify default values for a specific domain or entity, edit the files in src/types/entities or entitiesByDomain. For example, you can find custom state properties for specific entities (like Vacuum) in entitiesByDomain/index.ts. These changes will propagate across hooks and components.