OpenParable
Skip to content
← Back to skills

Ha Frontend Contexts

Development
ha-frontend-contexts

Ha Frontend Contexts is an Agent Skill for development published in the home-assistant/frontend repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Home Assistant frontend Lit context and hass migration guidance. Use when adding or changing component state access, replacing hass reads, consuming entity or registry contexts, or reviewing rerender behavior.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/home-assistant/frontend/blob/HEAD/.agents/skills/ha-frontend-contexts/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ha-frontend-contexts, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

HA Frontend Contexts

Use this skill when a component reads Home Assistant state, registries, localization, services, config, UI data, connection state, or API helpers.

Goal

Move leaf components away from the broad hass: HomeAssistant object. Broad hass access rerenders components for unrelated changes, hides the data a component depends on, and makes tests harder to mock.

Container components may keep hass when they own it and feed providers. Leaf components should consume the narrowest context that covers their reads.

Core Files

  • Context definitions: src/data/context/index.ts
  • Entity-scoped consume helpers: src/common/decorators/consume-context-entry.ts
  • Transform decorator: src/common/decorators/transform.ts
  • Canonical migration example: src/panels/lovelace/cards/hui-button-card.ts
  • Providers are wired by contextMixin on HassBaseEl; consumers do not wire providers manually.

Context Selection

ContextReplaces
statesContexthass.states
entitiesContext, devicesContext, areasContext, floorsContexthass.entities, hass.devices, hass.areas, hass.floors
registriesContextall four registries together
servicesContexthass.services
internationalizationContexthass.localize, hass.locale, hass.language
formattersContextentity and attribute formatters
configContexthass.config, hass.user, hass.auth, hass.userData
connectionContexthass.connection, hass.connected, hass.hassUrl
apiContexthass.callService, hass.callApi, hass.callWS, hass.sendWS, hass.fetchWithAuth
uiContextthemes, selected theme, panels, sidebar, and UI state
narrowViewportContextnarrow-layout boolean

Lazy contexts subscribe on first consumer and tear down after the last consumer: labelsContext, fullEntitiesContext, configEntriesContext, and manifestsContext.

The single-field contexts such as localizeContext, themesContext, and userContext are deprecated. Use grouped contexts instead.

Consumption Patterns

Use entity-scoped helpers when the component watches an entity id held on the host:

@state() @consumeEntityState({ entityIdPath: ["_config", "entity"] })
private _stateObj?: HassEntity;

@state() @consumeEntityRegistryEntry({ entityIdPath: ["_config", "entity"] })
private _entity?: EntityRegistryDisplayEntry;

@state() @consumeLocalize()
private _localize!: LocalizeFunc;

For a single field from a grouped context, pair @consume with @transform:

@state()
@consume({ context: uiContext, subscribe: true })
@transform<HomeAssistantUI, Themes>({ transformer: ({ themes }) => themes })
private _themes!: Themes;

Use @transform with watch when the transformer depends on a host property, such as a computed entity id. consumeEntityState only watches the first path segment.

To consume a whole group untransformed, omit @transform and type the field as ContextType<typeof statesContext> or the matching context type.

Review Checklist

  • The component consumes the narrowest context needed for the data it reads.
  • A broad hass property is kept only when the component is a container or external API requires it.
  • Entity-scoped reads use the consume helpers rather than ad hoc context transforms.
  • Context fields are marked @state() so updates trigger rendering.
  • Tests and mocks only provide the data the component actually consumes.