listhen

Elegant HTTP Listener

Discover other projects

listhen

👂 listhen

Elegant http listener

npm version npm downloads Github Actions Codecov

✔️ Promisified interface for listening and closing server

✔️ Works with express/connect or plain http handle function

✔️ Support HTTP and HTTPS

✔️ Automatically assign a port or fallback to human friendly alternative (with get-port-please)

✔️ Automatically generate listening URL and show on console

✔️ Automatically copy URL to clipboard

✔️ Automatically open in browser (opt-in)

✔️ Automatically generate self-signed certificate

✔️ Automatically detect test and production environments

✔️ Automatically close on exit signal

✔️ Gracefully shutdown server with http-shutdown

Install

Install using npm or yarn:

npm i listhen
# or
yarn add listhen

Import into your Node.js project:

// CommonJS
const { listen } = require('listhen')

// ESM
import { listen } from 'listhen'

Usage

Function signature:

const { url, getURL, server, close } = await listen(handle, options?)

Plain handle function:

listen((_req, res) => {
  res.end('hi')
})

With express/connect:

const express = require('express')
const app = express()

app.use('/', ((_req, res) => {
  res.end('hi')
})

listen(app)

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

  • Default: false

Listen with https protocol. By default uses a self-signed certificated.

certificate

Path to https certificate files { key, cert }

selfsigned

Options for self-signed certificate (see selfsigned).

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 💖