home-assistant-lazy-context

name: home-assistant-lazy-context description: 'Home Assistant frontend lazy-context, memoization, and hass removal guidance. Use when migrating Lit components from hass!: HomeAssistant, .hass=${...}, or broad hass access to context slices.'

Home Assistant Lazy Context

Use this skill when reviewing or editing Home Assistant frontend context, memoization, or hass removal work.

Default Migration Rule

When a component adopts context, remove its hass property and replace each this.hass.* access with the narrowest context or value that supplies that data. Also remove .hass=${...} passthroughs to migrated child components; if a child still needs data, either migrate the child to context or pass a narrow prop such as localize, states, or Pick<HomeAssistant, "callWS">.

Do not keep hass!: HomeAssistant just to preserve the old public API unless the component is intentionally reused outside the app context tree or the user explicitly asks for compatibility.

Context Architecture (src/data/context/index.ts)

Three tiers of Lit contexts provided by context-mixin.ts:

Core Contexts (always subscribed)

Lazy Contexts (subscribed only when consumed)

Managed by LazyContextProvider -- WS subscription defers until first consumer, tears down after 5s idle when all consumers disconnect.

Deprecated Contexts

Do not use. Each has a @deprecated comment naming the replacement:

• connectionSingleContext → connectionContext
• localizeContext, localeContext → internationalizationContext
• configSingleContext, userContext, userDataContext, authContext → configContext
• themesContext, selectedThemeContext, panelsContext → uiContext

Entity Decorators (src/common/decorators/consume-context-entry.ts)

• @consumeEntityState({ entityIdPath }) — resolves entity ID from host config path, subscribes to statesContext, returns HassEntity
• @consumeEntityStates({ entityIdPath }) — same for array of entity IDs → HassEntity[]
• @consumeEntityRegistryEntry({ entityIdPath }) — subscribes to entitiesContext, returns EntityRegistryDisplayEntry
• @consumeLocalize() — subscribes to internationalizationContext and narrows it to LocalizeFunc

Use @consumeLocalize() when a component only needs localize. Use internationalizationContext directly when it also needs locale, language, translationMetadata, loadBackendTranslation, or loadFragmentTranslation.

Migration: Removing hass

When a component adopts context, the hass property is removed. This requires revising all sub-components and helpers it passes hass to.

Decision Tree for Sub-Components

1. Component can consume context directly (it's rendered in the app tree, not reused across unrelated trees):

   • Remove hass property, add @consume decorators for each needed slice.
   • Use ContextType<typeof fooContext> for typing.

2. Component is a shared utility (reused widely, context conversion would touch too many callers):

   • Pass the individual item as a prop when scope is small (e.g. localize: LocalizeFunc, states: HassEntities).
   • Pass Pick<HomeAssistant, "callWS" | "localize"> when the component needs a few unrelated slices and context is not viable.
   • Never pass the full HomeAssistant object.

3. Helper/utility functions (pure data functions):

   • Narrow the parameter from HomeAssistant to Pick<HomeAssistant, "callWS"> (or the single value needed).
   • This lets the consuming component pass its context slice directly (e.g. this._api) without reconstructing hass.
   • Prefer narrowing the helper over changing every caller — keeps the scope of the change small.

Narrowing Helpers to Avoid Scope Explosion

When a component adopts context, its helpers still need data. Rather than passing a reconstructed hass-like object or converting every caller, narrow the helper signature so the context slice satisfies it directly:

// BEFORE: helper accepts full hass
export const fetchDeviceTriggers = (hass: HomeAssistant, deviceId: string) =>
  hass.callWS<DeviceTrigger[]>({...});

// AFTER: helper accepts only what it uses
export const fetchDeviceTriggers = (
  hass: Pick<HomeAssistant, "callWS">,
  deviceId: string
) => hass.callWS<DeviceTrigger[]>({...});

The component then passes its context slice directly:

// Component consumes apiContext (which satisfies Pick<HomeAssistant, "callWS">)
@state()
@consume({ context: apiContext, subscribe: true })
private _api!: ContextType<typeof apiContext>;

// Passes directly — no reconstruction needed
const triggers = await fetchDeviceTriggers(this._api, deviceId);

This keeps the change focused: the dialog/panel adopts context, the helpers get narrowed types, and all other callers of those helpers still work unchanged (since HomeAssistant satisfies Pick<HomeAssistant, "callWS">).

When to Use Pick vs Individual Values

• Pick<HomeAssistant, "callWS"> — when the helper uses methods from a single context group and the existing param name hass stays readable. Keeps changes minimal.
• Individual value (e.g. states: HassEntities) — when passing a plain data map that the helper iterates/reads. More explicit, avoids the hass. prefix.
• Pick with multiple keys — avoid unless strictly necessary. If a helper needs "callWS" | "localize", consider splitting it or accepting the grouped context type directly.

Consumption Pattern

@state()
@consume({ context: apiContext, subscribe: true })
private _api!: ContextType<typeof apiContext>;

@state()
@consume({ context: internationalizationContext, subscribe: true })
private _i18n!: ContextType<typeof internationalizationContext>;

@state()
@consume({ context: statesContext, subscribe: true })
private _states!: ContextType<typeof statesContext>;

Usage: this._api.callWS(...), this._i18n.localize(...), this._states[entityId].

For localize-only components, prefer the helper:

@consumeLocalize()
private _localize!: LocalizeFunc;

Rules

General

• Preserve runtime behavior and public API shape except for the hass API intentionally removed by context migrations.
• Use the narrowest correct data source; prefer contexts, lazy contexts, and entity decorators over broad hass access.
• Do not use deprecated contexts; use the replacement named in @deprecated comments.
• Do not replicate hass or build local objects that mirror large parts of HomeAssistant.
• Do not add provider fallbacks when an existing app-level context/lazy context is already correct.
• Do not duplicate LazyContextProvider lifecycle behavior in feature components.
• Do not create wrapper helpers that only forward existing utility calls.

Typing

• Use ContextType<typeof context> for consumed context typing.
• Use required (!) when lifecycle guarantees availability; use optional (?) only when value can be genuinely absent.
• Avoid excessive defensive guards around required consumed contexts.
• For sub-components that can't use context, type props as narrow as possible: prefer LocalizeFunc over HomeAssistantInternationalization, prefer Pick<HomeAssistant, "callWS"> over HomeAssistant.

Memoization

• Pass explicit narrow inputs only (actual state slice, config, primitive, small arrays).
• Do not pass broad objects (hass, this, large mutable maps) into memoizeOne.
• Do not widen signatures with pass-through localize, language, locale, or config values when class/context access already exists.
• Do not add passthrough fields (_language, _locale, _config) only to route values into helpers.
• For rarely changed values like locale/config, read from existing class/context access at point of use.

Style

• Do not add unnecessary comments or abstractions.