HACS (Home Assistant Community Store) Documentation

HACS (Home Assistant Community Store) provides the following core functionalities for managing custom elements in Home Assistant:

• Discovery: Find new custom elements available in the community.
• Installation: Download and install new custom elements directly.
• Management: Update existing custom elements to newer versions or remove them from your system.
• Repository Hosting: Publish your own custom element repositories and create shortcuts to external repositories or issue trackers.

While not strictly required, publishing GitHub releases is highly recommended.

• With Releases: HACS will present users with a selection view showing the 5 latest releases alongside the default branch, making downloading and upgrading easier.
• Without Releases: HACS will default to using the files found in the repository's default branch.

HACS requires a GitHub account to perform authenticated requests to the GitHub API. This is necessary because unauthenticated requests are strictly rate-limited to only 60 requests per hour, which is insufficient for gathering information about available and downloaded repositories.

By using an authenticated request, HACS can access a much higher rate limit, ensuring reliable updates and repository discovery.

HACS relies on two distinct data sources to provide information about repositories and updates:

1. HACS Data: A centralized data source hosted at data-v2.hacs.xyz. It provides structured JSON data for standard HACS repository types (integrations, themes, etc.).
2. GitHub REST API: Used for fetching real-time information, specifically for custom repositories (repositories added manually by the user) and as a fallback mechanism if HACS Data is unavailable.

When you initiate a download for an element (such as an integration, dashboard, or template) in HACS, the following sequence occurs:

1. Directory Cleanup: The existing local target directory (folder) for that element is deleted.
2. Directory Creation: A new, empty local target directory is created.
3. File Download: All expected files for that specific element type are downloaded into the new directory.

Note that the specific files downloaded depend entirely on the element type (e.g., integrations will have different file structures than dashboards or templates).

HACS determines which version of your AppDaemon app to download based on the presence of GitHub releases:

• If your repository uses GitHub releases: HACS scans the content of the latest release. Users can choose to download specific versions from the last 5 releases or the default branch.
• If your repository has no releases: HACS scans the files in the branch marked as the default branch.

HACS provides a custom path, /hacsfiles/ (the /hacsfiles endpoint), for serving dashboard elements. While it functions similarly to the standard /local/ path, it includes specific optimizations:

• No Caching: The /hacsfiles endpoint instructs your browser to fetch a new version on every load, ensuring you always have the latest version.
• Automatic Compression: It automatically attempts to serve a .gz variant of the element to reduce file size and speed up transfers.

Example Comparison: If your element is located at www/community/dashboard/dashboard.js:

• Using /local/community/dashboard/dashboard.js serves the raw .js file.
• Using /hacsfiles/dashboard/dashboard.js utilizes HACS features like automatic .gz serving and cache busting.

HACS determines which files to download or upgrade based on the presence of GitHub releases:

• With Releases: HACS scans the content of the latest release. If multiple releases exist, users can choose to download specific versions from the last 5 releases or the default branch.
• Without Releases: HACS scans the files in the repository's default branch.

It is important to understand the distinction between HACS and Home Assistant 'Apps' to avoid configuration errors:

• HACS is an integration: It is used to manage content within Home Assistant.
• Apps are separate: HACS does not manage, install, or handle Home Assistant Apps.

These are two completely different concepts within the Home Assistant ecosystem.