### Install and Run ESPHome Designer Locally (npm)

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Use this command to install dependencies and start the local development server if you have cloned the full repository. Access the designer at http://localhost:5174.

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

--------------------------------

### Install and Run ESPHome Designer Locally (Python)

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Serve the frontend directly using Python's HTTP server if you only have the `custom_components` folder. Access the designer at http://localhost:8000. Connect to Home Assistant via Editor Settings.

```bash
cd custom_components/esphome_designer/frontend
python3 -m http.server 8000
```

--------------------------------

### Install Optional Python Test Dependencies

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Run this command to install optional Python test dependencies into your virtual environment.

```bash
npm run python:deps
```

--------------------------------

### Install Git Hooks

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Enable the repository hook to automatically enforce the pre-push verification on every push.

```bash
npm run hooks:install
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Install optional Python dependencies for the full Python panel/auth test flow. These scripts prefer the repository's `.venv` but will fall back to your active Python environment.

```bash
npm run python:deps
```

--------------------------------

### Display Protocol Warning for file:// Access

Source: https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/dist/index.html

Adds a visual warning to the page when accessed via the `file://` protocol, indicating potential limitations and suggesting alternative installation methods.

```javascript
if (window.location.protocol === 'file:') {
 document.addEventListener('DOMContentLoaded', () => {
 const warning = document.createElement('div');
 warning.style.cssText = ` position: fixed; top: 10px; left: 50%; transform: translateX(-50%); background: #ff9f43; color: #333; padding: 12px 36px 12px 24px; border-radius: 8px; z-index: 10000; font-weight: bold; box-shadow: 0 4px 15px rgba(0,0,0,0.2); text-align: center; line-height: 1.4; border: 1px solid rgba(0,0,0,0.1); font-family: sans-serif; font-size: 14px; `;
 warning.innerHTML = ` <span>⚠️ Running from local file. Full functionality is not guaranteed.<br> <small>For the best experience, install via HACS or use a local server.</small></span> <button onclick="this.parentElement.remove()" style=" position: absolute; right: 8px; top: 50%; transform: translateY(-50%); background: none; border: none; font-size: 18px; cursor: pointer; color: #333; padding: 4px; line-height: 1; ">&times;</button> `;
 document.body.appendChild(warning);
 console.warn("[CORS] Running on file:// protocol. Some features may be limited.");
 });
}
```

--------------------------------

### Prepare for Release (Skip Hassfest)

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Perform checks for release version surfacing, rebuild the distribution, run core checks, and generate an upload manifest. Use this for manual GitHub uploads and release/version bumps.

```bash
npm run release:prepare:skip-hassfest
```

--------------------------------

### Prepare for Release (Full)

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Perform release preparation including Hassfest, for full local Actions parity. This command should be used if Docker is running.

```bash
npm run release:prepare
```

--------------------------------

### Prepare for Release (Skip Hassfest)

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Prepare for manual GitHub uploads, especially version bumps or frontend changes. This command rebuilds the frontend bundle, checks release surfaces, runs local CI checks, and generates a manifest file for the shipped distribution.

```bash
npm run release:prepare:skip-hassfest
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Execute the production build script to generate assets and update build metadata.

```bash
npm run build
```

--------------------------------

### Define a Hardware Recipe with Lambda Placeholder

Source: https://github.com/koosoli/esphomedesigner/blob/main/hardware_recipes_guide.md

Use this structure to define your hardware configuration while leaving a placeholder for the Designer to inject UI code. System infrastructure sections should be commented out to prevent conflicts.

```yaml
# wifi:
#   ssid: ...
#
# api:
#
# captive_portal:

display:
  - platform: ...
    # ... other display settings ...
    lambda: |-
      # __LAMBDA_PLACEHOLDER__
```

--------------------------------

### Prepare for Release (Include Hassfest)

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Prepare for release, including Hassfest, if Docker is available. This command performs the same checks as `release:prepare:skip-hassfest` and additionally runs Hassfest.

```bash
npm run release:prepare
```

--------------------------------

### Run Pre-push Verification

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Execute the broader pre-push flow, including baseline governance, dist freshness check, Home Assistant integration metadata verification, and Hassfest via Docker.

```bash
npm run verify:pre-push
```

--------------------------------

### Run Python Test Suite

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Execute the Python test suite using the same discovery path as the quality gate.

```bash
npm run python:test
```

--------------------------------

### Run Frontend Typecheck

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Perform a broad frontend configuration check. Use this if you want to iterate locally on frontend checks without running the full quality suite.

```bash
npm run typecheck
```

--------------------------------

### Run All Tests

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Execute the full regression suite to verify schema parity and ensure changes do not break legacy behavior. This command verifies the schema hash without rewriting it.

```bash
npm test
```

--------------------------------

### Run Strict Frontend Typecheck

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Perform a stricter opt-in core check for frontend code. Use this for more rigorous local iteration on frontend checks.

```bash
npm run typecheck:strict
```

--------------------------------

### Define Hardware Recipe Metadata Header

Source: https://github.com/koosoli/esphomedesigner/blob/main/hardware_recipes_guide.md

Include this metadata block at the top of your YAML file to inform the Designer about device capabilities and display properties.

```yaml
# ============================================================================
# TARGET DEVICE: Waveshare Touch LCD 7"
# Name: Waveshare Touch LCD 7"
# Resolution: 800x480
# Shape: rect
# Orientation: landscape
# Inverted: false
# Dark Mode: disabled
# Refresh Interval: 300
# ============================================================================
```

--------------------------------

### Verify Distribution Bundle Freshness

Source: https://github.com/koosoli/esphomedesigner/blob/main/CONTRIBUTING.md

Check if the shipped UI bundle is current by verifying `custom_components/esphome_designer/frontend/dist/build-meta.json` against current frontend sources and manifest-backed dist files. This command is relevant if you changed frontend source, Vite config, or anything affecting the shipped UI bundle.

```bash
npm run verify:dist
```

--------------------------------

### Run Frontend and Schema Tests

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Execute the frontend test suite and schema checks. Use `npm run schema:check` to inspect schema changes and `npm run schema:update` to update baselines.

```bash
npm test
```

```bash
npm run schema:check
```

```bash
npm run schema:update
```

--------------------------------

### Polyfill crypto.randomUUID and Handle file:// Protocol

Source: https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/index.html

Provides a fallback for crypto.randomUUID in non-secure contexts and displays a warning banner when the application is accessed via the file:// protocol.

```javascript
// Polyfill for crypto.randomUUID for non-secure contexts (HTTP/Ingress) if (!window.crypto.randomUUID) { window.crypto.randomUUID = function () { return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, c => (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16) ); }; } // Protocol Warning for file:// access if (window.location.protocol === 'file:') { document.addEventListener('DOMContentLoaded', () => { const warning = document.createElement('div'); warning.style.cssText = ` position: fixed; top: 10px; left: 50%; transform: translateX(-50%); background: #ff9f43; color: #333; padding: 12px 36px 12px 24px; border-radius: 8px; z-index: 10000; font-weight: bold; box-shadow: 0 4px 15px rgba(0,0,0,0.2); text-align: center; line-height: 1.4; border: 1px solid rgba(0,0,0,0.1); font-family: sans-serif; font-size: 14px; `; warning.innerHTML = ` <span>⚠️ Running from local file. Full functionality is not guaranteed.<br> <small>For the best experience, install via HACS or use a local server.</small></span> <button onclick="this.parentElement.remove()" style=" position: absolute; right: 8px; top: 50%; transform: translateY(-50%); background: none; border: none; font-size: 18px; cursor: pointer; color: #333; padding: 4px; line-height: 1; ">&times;</button> `; document.body.appendChild(warning); console.warn("[CORS] Running on file:// protocol. Some features may be limited."); }); }
```

--------------------------------

### Compile ESPHome Project on PC

Source: https://github.com/koosoli/esphomedesigner/blob/main/README.md

Use this command to compile your ESPHome project on a PC if your Raspberry Pi lacks sufficient RAM. Ensure your project files are in a folder with no spaces in its path.

```powershell
python -m esphome compile C:\esphome_build\reterminal.yaml
```