listhen: HTTP Listener and Dev Server

Common errors

• Address already in use :::3000

  cause Another process is currently using the specified port (e.g., 3000).
  fix Specify a different port number in the `port` option, or omit the `port` option entirely to allow `listhen` to automatically find an available port using `get-port-please`.

• ERR_REQUIRE_ESM: require() of ES Module ... Not supported.

  cause Attempting to use `require()` to import an ES Module package (or a package configured primarily for ESM) in a CommonJS context.
  fix Ensure your project is configured for ES Modules (add `"type": "module"` to your `package.json` file) and use `import` statements. If you must use CommonJS, verify the package version is fully compatible with CommonJS or consider using a bundler like Webpack/Rollup that handles module interoperability.

• Error: Certificate is not trusted

  cause You are using `https: true` with a self-signed certificate, which browsers do not inherently trust.
  fix For development, bypass the browser security warning. For production, acquire and configure a valid, trusted SSL certificate by providing `cert` and `key` paths in the `https` option: `{ https: { cert: 'path/to/cert.pem', key: 'path/to/key.pem' } }`.

Warnings

• gotcha The `showURL`, `open`, and `clipboard` options are automatically disabled (`false`) when `listhen` detects a `test` or `production` environment, regardless of explicitly setting them to `true`. This prevents unintended side effects in CI/CD or deployed applications.
  Fix: If you require these features in a non-development environment, you must explicitly set `isTest: false` and `isProduction: false` in the options object, though this is generally not recommended.
• gotcha When `https: true` is used without providing custom certificates, `listhen` generates a self-signed SSL certificate. Most browsers will display a 'not trusted' warning for these certificates, requiring manual acceptance.
  Fix: For development, accept the browser warning. For production or trusted environments, provide your own trusted SSL certificates using the `https: { cert, key }` option.
• gotcha The `hostname` option defaults to `'0.0.0.0'`, which makes the server accessible from external networks. If you intend for the server to be only accessible from the local machine, you should explicitly set `hostname: 'localhost'` or `hostname: '127.0.0.1'`.
  Fix: Set `hostname: 'localhost'` or `hostname: '127.0.0.1'` in your `listhen` options to restrict access to the local machine.

Install

• npm install listhen npm
• yarn add listhen yarn
• pnpm add listhen pnpm

Imports

• listen
  wrong:

  const { listen } = require('listhen')

  correct:

  import { listen } from 'listhen'

  While CommonJS `require` is supported in v1.x, the `unjs` ecosystem generally encourages ES Modules. Ensure proper `tsconfig.json` and `package.json` (`"type": "module"`) configurations for optimal TypeScript and ESM usage.
• listenAndWatch
  wrong:

  import listenAndWatch from 'listhen'

  correct:

  import { listenAndWatch } from 'listhen'

  This is a named export, not a default export. Use for development servers that require file watching and hot reloading capabilities.
• Listener
  wrong:

  import { Listener } from 'listhen'

  correct:

  import type { Listener } from 'listhen'

  When importing types in TypeScript, use `import type` to ensure the import is stripped from the compiled JavaScript, preventing unnecessary runtime dependencies.

Quickstart

Demonstrates how to create an h3 application and listen to it using `listhen`, showcasing essential options like port, hostname, URL clipboard copying, and automatic browser opening.

import { createApp, eventHandler } from "h3";
import { listen } from "listhen";

const app = createApp();

app.use(
  "/",
  eventHandler(() => "Hello world from listhen and h3!")
);

async function startServer() {
  const listener = await listen(app, {
    port: process.env.PORT ? parseInt(process.env.PORT) : 3000, // Use process.env.PORT or fallback to 3000
    hostname: process.env.HOST || "0.0.0.0",
    clipboard: true, // Copy URL to clipboard in dev
    open: true,      // Open in browser in dev
    showURL: true,   // Show URL in console
    https: false     // Set to true for self-signed HTTPS in dev
  });
  console.log(`Server listening on ${listener.url}`);

  // Graceful shutdown on common signals
  process.on('SIGINT', () => { listener.close(); console.log('Server gracefully shutting down...'); });
  process.on('SIGTERM', () => { listener.close(); console.log('Server gracefully shutting down...'); });
}

startServer();