# Ha Frontend Types

> Home Assistant frontend TypeScript conventions. Use when defining or reviewing backend data contracts, optional schemas, shared types, assertions, or Lit lifecycle types.

- Skill: `home-assistant/ha-frontend-types` (Agent Skill)
- Install (CLI): `npx skillmds@latest add home-assistant/ha-frontend-types`
- Raw SKILL.md: https://api.skillmd.com/api/skills/home-assistant/ha-frontend-types/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: home-assistant (https://skillmd.com/u/home-assistant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/home-assistant/ha-frontend-types

---


# HA Frontend Types

Use this skill for Home Assistant-specific TypeScript contracts and type choices.

## Home Assistant Data Contracts

Verify data contracts against the source that owns them, such as Home Assistant Core, Supervisor, a WebSocket handler, or an exported component type. Do not shape a type around assumptions made by its current frontend consumers.

- Match required, optional, nullable, and defaulted fields to the producer and runtime contract. Preserve optional configuration fields when omission is supported and has defined behavior.
- Use distinct request and response types when their wire shapes differ.
- When changing a shared contract, check affected consumers, tests, fixtures, and mocks.

## Reuse Home Assistant Contracts

- Reuse the canonical Home Assistant type when one exists. Define shared contract types in the data or API module that owns them.
- Reuse types exported by components and helpers rather than reconstructing their payloads. For event types, follow `ha-frontend-events`.
- When one domain contract is used across modules, define and export it from the module that owns that contract.

Prefer an existing owning contract. Introduce a frontend-specific type when the frontend shape or boundary genuinely differs.

## Assertions

Prefer accurate types and runtime narrowing. Use assertions or TypeScript suppressions at boundaries where the runtime invariant is understood but cannot be expressed cleanly; keep them narrow and explain non-obvious invariants.

## Lit Lifecycle Types

For Lit lifecycle methods that receive changed properties, use `PropertyValues<this>` when the method only needs public reactive properties:

```ts
protected willUpdate(changedProperties: PropertyValues<this>) {
  // ...
}
```

Use unparameterized `PropertyValues` when the method inspects private or protected reactive properties, which are not keys of `this`. Do not add assertions solely to retain `PropertyValues<this>`.

## Enforced Baseline

Use `import type` for type-only imports. This is enforced by the repository ESLint configuration.