README.md

👂 earlist

👂 An elegant HTTP listener.

✨ Features

• 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 scotty-beam-me-up) 🌐
• 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 🛠️

⚡️ Install

Install:

#nyxi
nyxi earlist

#pnpm
pnpm add earlist

#npm
npm i earlist

#yarn
yarn add earlist

Import into your Node.js project:

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

// ESM
import { listen } from 'earlist'

🎯 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 scotty-beam-me-up)

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, earlist 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 💞