Home

Awesome

👂 listhen

<!-- automd:badges -->

npm version npm downloads

<!-- /automd -->

Elegant HTTP listener!

👉 Online Playground

Features

✅ Dev server with HMR, static, WebSockets and TypeScript support with <a href="https://github.com/unjs/jiti">unjs/jiti</a><br>

✅ Works with Node.js, Express, and <a href="https://github.com/unjs/h3">unjs/h3</a> out of the box <br>

✅ Show the QR code of the public URL with <a href="https://github.com/unjs/uqr">unjs/uqr</a><br>

✅ Tunnel your local server to the world with <a href="https://github.com/unjs/untun">unjs/untun</a><br>

✅ Assign a port or fallback to a nicer alternative with <a href="https://github.com/unjs/get-port-please">unjs/get-port-please</a>

✅ Gracefully shutdown Server with <a href="https://github.com/thedillonb/http-shutdown">http-shutdown</a><br>

✅ Zero Config WebSockets with <a href="https://github.com/unjs/crossws">unjs/crossws</a>

✅ Copy the URL to the clipboard<br>

✅ HTTPS support with self-signed certificates<br>

✅ Open URL in browser<br>

✅ Detect test and production environments to auto-adjust behavior<br>

✅ Close on the exit signal<br>

<div align="center"> <img width="100%" src="./.assets/screenshot.png"> </div>

Quick Usage (CLI)

You can run your applications in localhost with TypeScript support and watch mode using listhen CLI:

Create index.ts:

export default (req, res) => {
  res.end("Hello World!");
};

or using unjs/h3:

import { createApp, eventHandler } from "h3";

export const app = createApp();

app.use(
  "/",
  eventHandler(() => "Hello world!"),
);

or use npx to invoke listhen command:

npx listhen -w ./index.ts

Usage (API)

Install package:

# pnpm
pnpm i listhen

# npm
npm i listhen

# yarn
yarn add listhen

Import into your Node.js project:

// CommonJS
const { listen, listenAndWatch } = require("listhen");

// ESM
import { listen, listenAndWatch } from "listhen";
const handler = (req, res) => {
  res.end("Hi!")
}

// listener: { url, getURL, server, close, ... }
const listener = await listen(handler, options)

Options

port

Port to listen.

hostname

Default hostname to listen.

https

Listen on HTTPS with SSL enabled.

Self-Signed Certificate

By setting https: true, listhen will use an auto-generated self-signed certificate.

You can set https to an object for custom options. Possible options:

User-Provided Certificate

Set https: { cert, key } where the cert and key are paths to the SSL certificates. With an encrypted private key, you also need to set passphrase on the https object.

To provide a certificate stored in a keystore set https: { pfx } with a path to the keystore. When the keystore is password protected also set passphrase.

You can also provide an inline cert and key instead of reading from the filesystem. In this case, they should start with --.

showURL

Show a CLI message for the listening URL.

baseURL

open

Open the URL in the browser. Silently ignores errors.

clipboard

Copy the URL to the clipboard. Silently ignores errors.

isTest

Detect if running in a test environment to disable some features.

autoClose

Automatically close when an exit event, SIGTERM, SIGINT or SIGHUP signal is received in the process.

publicURL

The public URL to show in the CLI output

qr

Print QR Code for public address.

public

When enabled, listhen tries to listen to all network interfaces. You can also enable this option using --host CLI flag.

ws

Enable experimental WebSocket support using unjs/crossws or node upgrade handler.

Option can be a function for Node.js upgrade handler ((req, head) => void) or an Object to use CrossWS Hooks.

When using dev server CLI, you can easily use --ws and a named export called websocket to define CrossWS Hooks with HMR support!

License

<!-- automd:contributors license=MIT author="pi0" -->

Published under the MIT license. Made by @pi0 and community 💛 <br><br> <a href="https://github.com/unjs/listhen/graphs/contributors"> <img src="https://contrib.rocks/image?repo=unjs/listhen" /> </a>

<!-- /automd --> <!-- automd:with-automd -->

🤖 auto updated with automd

<!-- /automd -->