AGENTS.md · Koenkk/zigbee2mqtt

Sections

1. Project Overview
2. Setup Commands
3. Development Workflow
4. Testing Instructions
5. Code Style Guidelines
6. Build and Deployment
7. Architecture Patterns
8. Pull Request Guidelines
9. Working with Device Support
10. Debugging and Troubleshooting
11. Critical Version Requirements
12. Additional Notes

First lines (shown under the repo's GPL-3.0 license)

# AGENTS.md

## Project Overview

Zigbee2MQTT is a Zigbee to MQTT bridge that allows you to use your Zigbee devices without the vendor's bridge or gateway. It bridges events and allows you to control Zigbee devices via MQTT, integrating them with any smart home infrastructure.

### Architecture

- **Language**: TypeScript 5.9.3 compiled to JavaScript (ES modules with NodeNext resolution)
- **Runtime**: Node.js (versions 20, 22, or 24)
- **Package Manager**: pnpm 10.12.1 (strictly enforced via `packageManager` field)
- **Core Dependencies**:
  - `zigbee-herdsman` (6.2.0 - exact version, handles Zigbee adapter communication)
  - `zigbee-herdsman-converters` (25.42.0 - exact version, device definitions)
  - `mqtt` (5.14.1 - MQTT client)
  - `winston` (3.18.3 - logging)

### Project Structure

```
lib/                    # TypeScript source code
├── controller.ts       # Main controller orchestrating components
├── mqtt.ts            # MQTT client management
├── zigbee.ts          # Zigbee network management
├── state.ts           # State management
├── eventBus.ts        # Event-driven communication
├── extension/         # Extension system (plugins)
│   └── extension.ts   # Abstract base class
├── model/             # Domain models (Device, Group)
├── util/              # Utility functions
└── types/             # TypeScript type definitions
test/                  # Vitest test files with mocks
data/                  # Runtime configuration and database
dist/                  # Compiled JavaScript output
```

## Setup Commands

### Prerequisites

- Node.js version 20, 22, or 24
- pnpm 10.12.1 (will be auto-installed via corepack if not present)

### Installation

```bash
# Install dependencies (uses pnpm lockfile)
pnpm install --frozen-lockfile

# For development without lockfile restrictions
pnpm install
```

### Initial Build

```bash
# Full build (TypeScript compilation + hash generation)
pnpm run build

# Build type definitions only
pnpm run build:types
```

## Development Workflow

### Starting Development

```bash
# Watch mode - recompile on file changes
pnpm run build:watch

# In another terminal, start Zigbee2MQTT
pnpm start
```

### Code Quality Checks

```bash
# Run Biome linter and formatter (check only)
pnpm run check

# Auto-fix linting and formatting issues
pnpm run check:w

# The check runs with --error-on-warnings flag
# Configuration: biome.json (4-space indent, 150 line width, no bracket spacing)
```

### Clean Build

```bash
# Remove build artifacts
pnpm run clean

# Removes: coverage/, dist/, tsconfig.tsbuildinfo
```

## Testing Instructions

### Running Tests

```bash
# Run all tests once
pnpm test

# Run tests with coverage report
pnpm run test:coverage

# Watch mode - re-run tests on changes
pnpm run test:watch

# Run benchmarks
pnpm run bench
```

### Test Requirements

- **Coverage**: 100% code coverage is enforced (configured in `test/vitest.config.mts`)
- **Framework**: Vitest 3.1.1 with @vitest/coverage-v8
- **Test Files**: Located in `test/` directory with `.test.ts` extension
- **Mocks**: Centralized in `test/mocks/` directory
- **Coverage Report**: Generated in `coverage/` directory (HTML report at `coverage/index.html`)

### Running Specific Tests

```bash
# Run tests matching a pattern
pnpm vitest run -t "test name pattern" --config ./test/vitest.config.mts

# Run specific test file
pnpm vitest run test/controller.test.ts --config ./test/vitest.config.mts

# Focus on one test area in watch mode
pnpm vitest watch -t "Extension" --config ./test/vitest.config.mts
```

## Code Style Guidelines

### TypeScript Conventions

- **Module System**: ES modules with NodeNext resolution
- **Target**: ESNext
- **Strict Mode**: Enabled (`noImplicitAny`, `noImplicitThis`)
- **Decorators**: Experimental decorators enabled (used for `@bind` from `bind-decorator`)

### Import Order

1. Node.js built-in modules (with `node:` prefix)
2. Third-party libraries
3. Type-only imports from external packages (using `type` keyword)
4. Internal absolute imports
5. Type-only imports from internal modules

Example:
```typescript
import fs from "node:fs";
import bind from "bind-decorator";
import type {IClientOptions} from "mqtt";
import {connectAsync} from "mqtt";
import type {Zigbee2MQTTAPI} from "./types/api";