listhen

👂 listhen

An elegant HTTP listener.

Features

• Built-in CLI To run your applications with watch mode and typescript support (with unjs/jiti)
• Promisified interface for listening and closing server
• Work with express/connect or plain http handle function
• Support HTTP and HTTPS
• Assign a port or fallback to human friendly alternative (with unjs/get-port-please)
• Generate listening URL and show on console
• Copy URL to clipboard (dev only by default)
• Open URL in browser (opt-in)
• Generate self-signed certificate
• Detect test and production environments
• Close on exit signal
• Gracefully shutdown server with http-shutdown

Quick Usage (CLI)

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

Create app.ts:

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

Use npx to invoke listhen command:

npx listhen -w ./app.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(handle, options?)

Options

port

• Default: process.env.PORT or 3000 or memorized random (see get-port-please)

Port to listen.

hostname

• Default: process.env.HOST || '0.0.0.0'

Default hostname to listen.

https

• Type: Boolean | Object
• Default: false

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:

• domains: (Array) Default is ['localhost', '127.0.0.1', '::1'].
• validityDays: (Number) Default is 1.

User Provided Certificate

Set https: { cert, key } where cert and key are path to the ssl certificates.

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

showURL

• Default: true (force disabled on test environment)

Show a CLI message for listening URL.

baseURL

• Default: /

open

• Default: false (force disabled on test and production environments)

Open URL in browser. Silently ignores errors.

clipboard

• Default: false (force disabled on test and production environments)

Copy URL to clipboard. Silently ignores errors.

isTest

• Default: process.env.NODE_ENV === 'test'

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

autoClose

• Default: true

Automatically close when an exit signal is received on process.

License

MIT. Made with 💖