# listening-on

> Print server url with local and network ip address

Latest version **2.1.0** (published 2025-11-12) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install listening-on
pnpm add listening-on
yarn add listening-on
bun add listening-on
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2025-11-12 |
| First published | 2021-06-03 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 11 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Beeno Tung |
| Maintainers | beenotung |
| Keywords | port, dev tool, running-at, console, report, typescript |

## Links

- npm: https://www.npmjs.com/package/listening-on
- Repository: https://github.com/beenotung/listening-on
- Homepage: https://github.com/beenotung/listening-on#readme
- Issues: https://github.com/beenotung/listening-on/issues
- npm.io page: https://npm.io/package/listening-on

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2025-11-12
- 2.0.9 — 2022-07-06
- 2.0.8 — 2022-05-20
- 2.0.7 — 2022-04-28
- 2.0.6 — 2022-04-28
- 2.0.5 — 2022-04-23
- 2.0.4 — 2022-04-23
- 2.0.3 — 2022-04-23
- 2.0.2 — 2021-06-20
- 2.0.1 — 2021-06-20
- 2.0.0 — 2021-06-20
- 1.0.3 — 2021-06-18
- 1.0.2 — 2021-06-03
- 1.0.1 — 2021-06-03
- 1.0.0 — 2021-06-03

## README

# listening-on

Discover local and network interface addresses and print friendly URLs for your services.

[![npm Package Version](https://img.shields.io/npm/v/listening-on)](https://www.npmjs.com/package/listening-on)
[![npm Package Version](https://img.shields.io/bundlephobia/min/listening-on)](https://bundlephobia.com/package/listening-on)
[![npm Package Version](https://img.shields.io/npm/dy/listening-on)](https://www.npmtrends.com/listening-on)

Plain node.js alternative to [running-at](https://www.npmjs.com/package/running-at) with reusable network interface discovery.

This package doesn't rely on `execa` and `ip`, hence more portable.

## Installation

```bash
## with npm
npm i listening-on

## or with pnpm
pnpm i listening-on

## or with yarn
yarn add listening-on
```

## Usage Example

### Print web server URLs

Named import example:

```typescript
import express from 'express'
import { print } from 'listening-on'

const PORT = +process.env.PORT! || 3000
const app = express()

app.use(express.static('public'))

app.listen(PORT, () => {
  print(PORT)
  /* will print out below lines:
listening on http://127.0.0.1:8100 (lo)
listening on http://192.168.59.46:8100 (wlp3s0)
    */
})
```

commonjs compatible import example:

```typescript
import * as listeningOn from 'listening-on'

listeningOn.print(PORT)

// or simply use require
require('listening-on').print(PORT)
```

### Reuse the discovered addresses

```typescript
import { scan_host } from 'listening-on'

scan_host({
  family: 'all',
  onAddress: ({ host }) => {
    // do something with the address
    appendToCaddyFile(host)
  },
})
```

Possible use cases:

- Print service URLs to the console for development.
- Generate upstream entries for a Caddyfile automatically.
- Feed bootstrap peers into a P2P network discovery list.
- Pre-populate environment configs or service discovery registries with your live IPs.

## API Reference (TypeScript)

```typescript
export function print(port_or_options: number | PrintOptions): void

export function scan_host(options: ScanOptions): void

export type PrintOptions = {
  port: number
  // default http
  protocol?: Protocol | string
  // default IPv4
  family?: Family | 'all'
}

export type Protocol = 'http' | 'https' | 'ws' | 'wss' | 'tcp' | 'udp'

export type Family = 'IPv4' | 'IPv6'

export type ScanOptions = {
  // default IPv4
  family?: Family | 'all'
  onAddress: (address: {
    /** interface name, e.g. lo, wlp3s0 */
    name: string
    /** ip address, e.g. 127.0.0.1, 192.168.59.46 */
    host: string
    /** ip family, e.g. IPv4, IPv6 */
    family: Family
  }) => void
}
```

## License

This is free and open-source software (FOSS) with
[BSD-2-Clause License](./LICENSE)

---
_Source: https://npm.io/package/listening-on · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._