Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
369c9be
refactor: remove all development-specific code and simplify integration
fx Jun 30, 2025
9ed86eb
chore: add .claude/settings.local.json to gitignore
fx Jun 30, 2025
18cd5f8
refactor: remove all -dashboard suffixes from the project
fx Jun 30, 2025
773ad3f
refactor: simplify naming and enable remote server deployment
fx Jun 30, 2025
ce39ffc
docs: remove all local build and installation references
fx Jun 30, 2025
5bcad3a
fix: update panel.js to work with any URL, not just localhost
fx Jun 30, 2025
0620f96
fix: use valid custom element name 'liebe-panel' instead of 'liebe'
fx Jun 30, 2025
1b4431b
fix: add null checks to prevent postMessage errors in panel.js
fx Jun 30, 2025
f38b857
fix: add null checks to route setter in panel.js
fx Jun 30, 2025
30a94a0
fix: use script source origin for iframe URL instead of window.locati…
fx Jun 30, 2025
13d3934
fix: handle iframe mode without WebSocket connection
fx Jun 30, 2025
f47624c
fix: check if stateChangeUnsubscribe is a function before calling
fx Jun 30, 2025
40680d8
fix: use updateEntities instead of non-existent setEntities
fx Jul 1, 2025
5e26cbf
fix: disable URL updates to prevent Home Assistant navigation issues
fx Jul 1, 2025
044063c
Revert "fix: disable URL updates to prevent Home Assistant navigation…
fx Jul 1, 2025
625d25d
fix: prevent Home Assistant navigation errors by not dispatching loca…
fx Jul 1, 2025
81c48d8
fix: correct URL handling to prevent double appending and support ini…
fx Jul 1, 2025
8041e47
fix: implement proper initial route loading with iframe requesting ro…
fx Jul 1, 2025
76ae624
chore: remove debug logging from panel.js and useHomeAssistantRouting
fx Jul 1, 2025
96cb316
fix: resolve linting and test failures
fx Jul 1, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -48,4 +48,7 @@ yarn-error.log*
lerna-debug.log*

# Misc
.env.sentry-build-plugin
.env.sentry-build-plugin

# Claude settings
.claude/settings.local.json
153 changes: 66 additions & 87 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,41 +122,55 @@ When creating a new epic with sub-issues:

## Development Workflow

### Home Assistant Development Setup
### Home Assistant Integration

For developing with Home Assistant integration:
Liebe runs as a web application that integrates with Home Assistant via custom panel.

```bash
npm run dev
```
#### Development Setup

1. **Start the development server**:

```bash
npm install
npm run dev
```

Add to Home Assistant configuration.yaml:
2. **Add to Home Assistant configuration.yaml**:

```yaml
panel_custom:
- name: liebe-panel
sidebar_title: Liebe Dev
sidebar_icon: mdi:heart
url_path: liebe
module_url: http://localhost:3000/panel.js
```

3. **Restart Home Assistant** and find "Liebe Dev" in the sidebar.

#### Production Deployment

Host Liebe on any web server:

```yaml
panel_custom:
- name: liebe-dashboard-dev
sidebar_title: Liebe Dev
sidebar_icon: mdi:react
url_path: liebe-dev
module_url: http://localhost:3000/dev-entry.js
- name: liebe-panel
sidebar_title: Liebe
sidebar_icon: mdi:heart
url_path: liebe
module_url: https://your-server.com/liebe/panel.js
```

This gives you:

- Hot module replacement
- Full hass object access (via postMessage bridge)
- Real-time updates as you code

Note: The custom element name in panel_custom must match the name in customElements.define()

### Starting a New Task

1. **Select Task from GitHub Project**

```bash
gh issue list --assignee @me
gh issue view <issue-number>
```
```bash
gh issue list --assignee @me
gh issue view <issue-number>
```

2. **Create Feature Branch**

Expand Down Expand Up @@ -199,9 +213,8 @@ Note: The custom element name in panel_custom must match the name in customEleme
```

3. **Home Assistant Integration Testing**
- Build the custom panel: `npm run build:ha`
- Copy built files to HA config: `cp -r dist/liebe-dashboard /config/www/`
- Update `configuration.yaml` with panel config
- Ensure dev server is running: `npm run dev`
- Update `configuration.yaml` with localhost:3000 URL
- Restart Home Assistant to test

### Completing a Task
Expand Down Expand Up @@ -290,63 +303,31 @@ Note: The custom element name in panel_custom must match the name in customEleme

### Home Assistant Custom Panel

#### Important: panel_iframe is Deprecated

Home Assistant has deprecated `panel_iframe` in favor of custom panels. Always use `panel_custom` for proper integration with full access to the `hass` object.
#### Custom Panel Integration

**Migration Guide:** If you're coming from `panel_iframe`, see [MIGRATION-FROM-IFRAME.md](/workspace/docs/MIGRATION-FROM-IFRAME.md) for detailed migration steps.
Home Assistant custom panels provide full access to the `hass` object and proper integration with the Home Assistant frontend. Always use `panel_custom` for dashboard integration.

#### Development Approaches

**1. Development Custom Panel (Recommended)**

This approach provides full hass access during development:

```yaml
# configuration.yaml
panel_custom:
- name: liebe-dashboard-dev
sidebar_title: Liebe Dev
sidebar_icon: mdi:react
url_path: liebe-dev
module_url: /local/liebe-dashboard-dev/custom-panel.js
config:
# Optional: Enable development mode
dev_mode: true
dev_url: 'http://localhost:3000'
```

Then use watch mode:

```bash
./scripts/dev-ha.sh watch --ha-config /path/to/ha/config
```

**2. Mock Server for Local Development**
**1. Local Development with Vite**

For UI development without Home Assistant:

```bash
# Start mock HA server
./scripts/dev-ha.sh mock-server

# In another terminal, start dev server
npm run dev
```

**3. Browser Extension for CORS**
This starts a local development server with hot module replacement. You can develop the UI components without needing Home Assistant.

If you need to bypass CORS during development:
**2. Integration Testing with Home Assistant**

1. Install a CORS extension (e.g., "CORS Unblock")
2. Configure it to allow HA → localhost:3000
3. Use the custom panel configuration
For testing the integration, ensure your dev server is running (`npm run dev`) and that Home Assistant is configured to use `http://localhost:3000/panel.js`.

#### Panel Registration

```javascript
customElements.define(
'liebe-dashboard-panel',
'liebe',
class extends HTMLElement {
set hass(hass) {
// Store hass object for API access
Expand Down Expand Up @@ -375,13 +356,15 @@ this._hass.callService('light', 'turn_on', {

#### Production Configuration

For production, host Liebe on your server:

```yaml
panel_custom:
- name: liebe-dashboard-panel
sidebar_title: Liebe Dashboard
sidebar_icon: mdi:view-dashboard
- name: liebe
sidebar_title: Liebe
sidebar_icon: mdi:heart
url_path: liebe
module_url: /local/liebe-dashboard/custom-panel.js
module_url: https://your-server.com/liebe/panel.js
config:
# Any custom configuration
theme: default
Expand Down Expand Up @@ -467,37 +450,33 @@ try {
- Panel not loading: Check module_url path
- No hass object: Ensure proper custom element setup
- State not updating: Check event subscriptions
- CORS errors: Use custom panel instead of iframe
- Dev server not accessible: Check firewall/network settings
- CORS errors: Ensure proper module_url path in configuration
- Build not updating: Clear browser cache or use hard reload

4. **Development Mode Issues**
- If using panel_iframe (deprecated): No hass object access
- Solution: Always use panel_custom for development
- For hot reload: Use watch build + symlink approach
4. **Development Tips**
- Use symlinks to avoid copying files during development
- Run build in watch mode for faster iteration
- Check browser console for module loading errors

## Development Best Practices

### Modern Home Assistant Development

1. **Never use panel_iframe** - It's deprecated and doesn't provide hass object access
2. **Always use panel_custom** for proper integration
3. **Development workflow options:**
- Watch build with symlinks (recommended)
- Mock server for UI-only development
- Home Assistant dev container for full integration testing
1. **Always use panel_custom** for proper integration with full hass object access
2. **Development workflow:**
- Run `npm run dev` for development with hot reload
- Configure Home Assistant to use `http://localhost:3000/panel.js`
- For production, deploy to a web server and update the URL

### Quick Development Setup

```bash
# One-time setup
./scripts/dev-ha.sh setup

# For development with real HA
./scripts/dev-ha.sh watch --ha-config /path/to/ha
# Start development server
npm install
npm run dev

# For UI-only development
./scripts/dev-ha.sh mock-server
npm run dev # In another terminal
# Configure Home Assistant to use http://localhost:3000/panel.js
# Restart Home Assistant
```

## Resources
Expand Down
64 changes: 31 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Liebe Dashboard
# Liebe

A custom Home Assistant dashboard built with TanStack Start and React in SPA mode.
A custom Home Assistant panel built with TanStack Start and React in SPA mode.

## Features

Expand All @@ -20,57 +20,55 @@ npm run dev
# Open http://localhost:3000
```

## Building for Home Assistant
Then add to your Home Assistant `configuration.yaml`:

```bash
# Build the custom panel
npm run build:ha

# Copy to Home Assistant
cp -r dist/liebe-dashboard /config/www/
```yaml
panel_custom:
- name: liebe-panel
sidebar_title: Liebe Dev
sidebar_icon: mdi:heart
url_path: liebe
module_url: http://localhost:3000/panel.js
```

Add to your `configuration.yaml`:
## Production

Host Liebe on any web server and add to your `configuration.yaml`:

```yaml
panel_custom:
- name: liebe-dashboard-panel
sidebar_title: Liebe Dashboard
sidebar_icon: mdi:view-dashboard
- name: liebe-panel
sidebar_title: Liebe
sidebar_icon: mdi:heart
url_path: liebe
module_url: /local/liebe-dashboard/custom-panel.js
module_url: https://your-server.com/liebe/panel.js
```

Restart Home Assistant and find "Liebe Dashboard" in the sidebar.
Restart Home Assistant and find "Liebe" in the sidebar.

## Development with Home Assistant
## Testing with Automation Tools

Start the development server:

```bash
npm run dev
```

Add to your Home Assistant `configuration.yaml`:
When testing Liebe with automation tools like Playwright, you may encounter authentication issues. To bypass authentication for testing purposes, you can configure Home Assistant to use trusted networks:

```yaml
panel_custom:
- name: liebe-dashboard-dev
sidebar_title: Liebe Dev
sidebar_icon: mdi:react
url_path: liebe-dev
module_url: http://localhost:3000/dev-entry.js
homeassistant:
auth_providers:
- type: trusted_networks
trusted_networks:
- 192.168.1.100/32 # Replace with your testing machine's IP
trusted_users:
192.168.1.100: # Replace with your testing machine's IP
- user_id_here # Replace with the user ID to auto-login as
allow_bypass_login: true
- type: homeassistant
```

**Restart Home Assistant** (required after adding/changing panel_custom).

This loads a wrapper that embeds your dev server in an iframe while providing access to the hass object via postMessage.
**⚠️ Security Warning**: Only use trusted networks in secure, controlled environments. This bypasses authentication for specified IP addresses.

## Scripts

- `npm run dev` - Start development server
- `npm run build` - Build SPA application
- `npm run build:ha` - Build custom panel for Home Assistant
- `npm run typecheck` - Run TypeScript type checking
- `npm run lint` - Run ESLint
- `npm run format` - Format code with Prettier
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"name": "liebe-dashboard",
"name": "liebe",
"private": true,
"sideEffects": false,
"type": "module",
Expand Down
Loading