{"id":16246,"library":"tplink-smarthome-api","title":"TP-Link Smart Home API","description":"This library provides a programmatic interface for controlling TP-Link Kasa smart home devices directly over the local network. It supports a wide range of devices including smart plugs (HS100, HS110, KP303), smart bulbs (LB100, KL125), and light strips (KL430), enabling local control without reliance on the TP-Link cloud services. The current stable version is 5.0.0, which targets Node.js environments version 16 and higher. While no explicit release cadence is documented, major version bumps suggest significant updates and potential breaking changes. A key differentiator is its focus on local LAN communication, offering increased privacy and potentially faster response times compared to cloud-dependent solutions. It ships with full TypeScript type definitions for an enhanced development experience, but importantly, does not support TP-Link Tapo devices.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/plasticrake/tplink-smarthome-api","tags":["javascript","tplink","kasa","home","smartplug","smartswitch","smartbulb","api","typescript"],"install":[{"cmd":"npm install tplink-smarthome-api","lang":"bash","label":"npm"},{"cmd":"yarn add tplink-smarthome-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add tplink-smarthome-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CJS `require` might still work, ESM `import` is the preferred and modern way, especially with Node.js >= 16. Type definitions are included for TypeScript.","wrong":"const { Client } = require('tplink-smarthome-api');","symbol":"Client","correct":"import { Client } from 'tplink-smarthome-api';"},{"note":"The `Device` class is an abstract base class for plugs and bulbs, primarily used as a type for type hinting; you do not instantiate it directly. Specific device instances are returned by `Client.getDevice()` or discovery events.","wrong":"import { Device } from 'tplink-smarthome-api';","symbol":"Device","correct":"import type { Device } from 'tplink-smarthome-api';"},{"note":"Interfaces like `DimmableLight`, `ColorLight`, or `BrightnessLight` are useful for type-checking device capabilities. These are TypeScript type imports, not runtime values.","wrong":"import { DimmableLight } from 'tplink-smarthome-api';","symbol":"DimmableLight","correct":"import type { DimmableLight } from 'tplink-smarthome-api';"}],"quickstart":{"code":"import { Client } from 'tplink-smarthome-api';\n\nconst client = new Client();\nconst deviceIp = process.env.KASA_DEVICE_IP ?? '192.168.1.100'; // Replace with your device's IP\n\nasync function controlDevice() {\n  console.log(`Attempting to connect to device at ${deviceIp}...`);\n  try {\n    const device = await client.getDevice({ host: deviceIp });\n    const sysInfo = await device.getSysInfo();\n    console.log(`Connected to ${sysInfo.alias} (${sysInfo.model})`);\n\n    const initialState = await device.getPowerState();\n    console.log(`Current power state: ${initialState ? 'ON' : 'OFF'}`);\n\n    const newState = !initialState;\n    await device.setPowerState(newState);\n    console.log(`Set power state to: ${newState ? 'ON' : 'OFF'}`);\n\n    if (device.deviceType === 'bulb' && 'setBrightness' in device) {\n      const currentBrightness = await (device as any).getBrightness();\n      console.log(`Current brightness: ${currentBrightness}%`);\n      await (device as any).setBrightness(50);\n      console.log('Set brightness to 50%');\n    }\n  } catch (error) {\n    console.error('Error controlling device:', error instanceof Error ? error.message : error);\n  }\n}\n\nasync function discoverDevices() {\n  console.log('Starting device discovery for 10 seconds...');\n  client.startDiscovery({ discoveryInterval: 1000, discoveryTimeout: 10000 });\n\n  client.on('device-new', async (device) => {\n    const sysInfo = await device.getSysInfo();\n    console.log(`[Discovery] Found new device: ${sysInfo.alias} (${sysInfo.host})`);\n    // Example: Turn on newly discovered smart plugs\n    if (device.deviceType === 'plug') {\n      await device.setPowerState(true);\n      console.log(`[Discovery] Turned on plug: ${sysInfo.alias}`);\n    }\n  });\n\n  client.on('device-online', (device) => console.log(`[Discovery] Device online: ${device.host}`));\n  client.on('device-offline', (device) => console.log(`[Discovery] Device offline: ${device.host}`));\n\n  setTimeout(() => {\n    client.stopDiscovery();\n    console.log('Discovery stopped.');\n  }, 10000);\n}\n\n// Run both examples\ncontrolDevice();\ndiscoverDevices();\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate the client, connect to a specific Kasa smart device by IP address, retrieve its system information, toggle its power state, and adjust brightness for bulbs. It also shows how to use the client's discovery feature to find devices on the local network and react to new devices coming online."},"warnings":[{"fix":"Upgrade your Node.js installation to version 16 or newer (e.g., using `nvm install 16` or higher).","message":"Version 5.0.0 and newer requires Node.js version 16 or greater. Users on older Node.js runtimes will encounter errors and should upgrade their Node.js environment.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your smart home devices are TP-Link Kasa models. For Tapo devices, alternative integration methods or libraries are required.","message":"TP-Link Tapo devices are explicitly NOT supported by this library. This API is designed for TP-Link Kasa devices (e.g., HS, KP, LB, KL series). Attempting to use it with Tapo devices will fail.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider disabling automatic firmware updates for critical Kasa devices. Monitor the library's GitHub repository for updates and community reports on breaking firmware changes.","message":"TP-Link does not officially support or provide a public API for local control, meaning firmware updates to your Kasa devices could potentially break compatibility with this library at any time. Exercise caution when updating device firmware if local control is critical.","severity":"gotcha","affected_versions":"all"},{"fix":"Check your network firewall rules, ensure devices are on the same subnet/VLAN, and consider assigning static IP addresses to your Kasa devices for direct connection. Rebooting your router can sometimes resolve discovery issues.","message":"Device discovery relies on UDP broadcast, which can be affected by network configuration (e.g., VLANs, router settings, firewalls). If devices aren't discovered, verify network settings or try specifying device IPs directly.","severity":"gotcha","affected_versions":"all"},{"fix":"Review the `CHANGELOG.md` for specific breaking changes and migration instructions when upgrading from previous major versions.","message":"Major version 5.x.x includes significant internal refactoring and API changes. While core functionalities remain, some internal structures or less common API calls might have changed. Always consult the official changelog when upgrading from 4.x.x.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"If using ES Modules (Node.js `--experimental-modules` or `\"type\": \"module\"` in `package.json`), use `import { Client } from 'tplink-smarthome-api';`. If using CommonJS, ensure you are using `const { Client } = require('tplink-smarthome-api');` and your `tsconfig.json` (if applicable) is set up for CJS output or `allowSyntheticDefaultImports: true`.","cause":"This typically occurs when trying to use CommonJS `require` syntax (`const { Client } = require(...)`) in an ES Module (`type: 'module'`) context, or vice-versa, without proper transpilation or configuration.","error":"TypeError: (0 , tplink_smarthome_api_1.Client) is not a constructor"},{"fix":"Double-check the device IP address, ensure the device is powered on and connected to the network, verify your network settings allow UDP communication, and confirm it's a Kasa device, not Tapo.","cause":"The client could not reach the specified device IP or discover any devices. Common causes include incorrect IP, device being offline, network configuration issues (firewall, VLANs), or the device being a Tapo model.","error":"Error: Device not found"},{"fix":"This library cannot control Tapo devices. You will need to find a different library or integration solution specifically for TP-Link Tapo products.","cause":"The `tplink-smarthome-api` library is specifically designed for TP-Link Kasa devices and does not support the Tapo line of products.","error":"Tapo device not responding or unexpected behavior."},{"fix":"Change your import statements from `const { Client } = require('tplink-smarthome-api');` to `import { Client } from 'tplink-smarthome-api';`. If you need to use `require` for other CJS modules, you might need to use a bundler or ensure your files are treated as CommonJS.","cause":"This error occurs when you attempt to use the `require()` function in a JavaScript file that is being interpreted as an ES Module (i.e., you have `\"type\": \"module\"` in your `package.json` or the file has a `.mjs` extension).","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}