Chii: Remote Chrome DevTools Framework

1.15.5 · active · verified Tue Apr 21

Chii is a remote debugging tool that serves as a modern alternative to Weinre, providing a full-featured web inspector experience by integrating the latest Chrome DevTools frontend. It enables developers to inspect and debug web pages across different environments or remote devices by injecting a small `target.js` script into the target page. The package is currently at version 1.15.5, indicating active development with frequent patch releases addressing fixes and minor feature additions (e.g., shadow DOM, dark mode) in its recent 1.x series. Chii operates by running a local server, acting as a proxy between the Chrome DevTools interface and the remote target, offering a familiar and powerful interface for debugging elements, network activity, console logs, and more, which is its primary differentiator against older remote debugging tools.

Common errors

```
ERR_CONNECTION_REFUSED
```
cause The client device (e.g., mobile phone) cannot connect to the Chii server, often due to incorrect IP address, firewall, or the server not running.

fix Verify the Chii server is running (`chii start`). Use the host machine's local network IP address in the target script (`<script src="//YOUR_IP:8080/target.js"></script>`). Check firewall settings on the host machine to allow traffic on the specified port.
```
chii: command not found
```
cause The `chii` command-line tool is not installed globally or is not in your system's PATH.

fix Install Chii globally using `npm install -g chii`. If already installed, ensure your system's PATH includes the directory where npm installs global packages.
```
Failed to load resource: net::ERR_CONNECTION_CLOSED (or similar network error for target.js)
```
cause `target.js` could not be fetched from the Chii server, usually because the server is down, the port is wrong, or the IP address in the script tag is incorrect.

fix Confirm the Chii server is active on the expected port (`chii start -p 8080`). Double-check the IP address and port in the `<script src="//host-machine-ip:8080/target.js"></script>` tag in your HTML.

Warnings

gotcha When debugging from a different device (e.g., a mobile phone), ensure you use the actual IP address of the host machine running Chii in the `<script src="//host-machine-ip:8080/target.js"></script>` tag, not `localhost` or `127.0.0.1`. Firewalls can also block connections, requiring explicit allowance for the specified port.
Fix: Use your host machine's local network IP address (e.g., `192.168.1.X`) and configure firewall rules to allow connections on the Chii port.
gotcha Older versions (prior to 1.15.2) had a 'ws dead loop' issue which could cause WebSocket connections to repeatedly fail, leading to an unstable debugging experience and potential performance degradation.
Fix: Upgrade Chii to version 1.15.2 or later to benefit from the fix for WebSocket stability.
gotcha Memory leaks were reported and fixed in versions prior to 1.14.0. Running older versions for extended periods could lead to increased resource consumption and potential crashes of the Chii server.
Fix: Update Chii to version 1.14.0 or newer to resolve known memory leak issues.
gotcha Version 1.15.5 includes a fix for 'invalid route path in koa router', indicating that prior versions might have experienced issues with certain API routes, potentially affecting the functionality of specific DevTools panels or features.
Fix: Upgrade to Chii 1.15.5 or later to ensure all routes and DevTools functionalities operate correctly.

Install

npm install chii npm
yarn add chii yarn
pnpm add chii pnpm

Imports

startServer
wrong:
```
const { startServer } = require('chii');
```
correct:
```
import { startServer } from 'chii';
```
For programmatic use to start the Chii debugging server. The package is primarily a CLI tool, but exposes this function for integration. ESM is preferred.
ChiiConstants
wrong:
```
import { Constants } from 'chii';
```
correct:
```
import * as ChiiConstants from 'chii/lib/constants';
```
Common utility constants used internally, which might be useful for advanced programmatic integrations. Direct import from `lib/constants` is typically required.
ChiiUtil
wrong:
```
import { util } from 'chii';
```
correct:
```
import * as ChiiUtil from 'chii/lib/util';
```
Various utility functions. Similar to constants, these are exposed from specific internal paths rather than the main entry point.

Quickstart

Demonstrates global installation, starting the Chii server, and injecting the target script into a web page for remote debugging.

npm install -g chii
chii start -p 8080

# In your target HTML file, inject the script:
# <script src="//host-machine-ip:8080/target.js"></script>

# Then, open http://localhost:8080 in your browser to start debugging.
# Replace 'host-machine-ip' with the actual IP address of the machine running Chii if debugging from a different device.

view raw JSON →