{"id":16104,"library":"listhen","title":"listhen: HTTP Listener and Dev Server","description":"listhen is an elegant HTTP listener for Node.js, designed to streamline local development server setups. It supports various server handlers including Node.js built-in HTTP, Express, and `unjs/h3`, making it highly adaptable for different project types. Currently at version 1.9.1, the package maintains an active release cadence, frequently publishing minor improvements and bug fixes, as evidenced by recent releases such as v1.9.1, v1.9.0, and v1.8.0. Key differentiators include its rich feature set out-of-the-box, such as hot module reloading (HMR) capabilities, static file serving, robust TypeScript support via `unjs/jiti`, and integrated WebSocket support through `unjs/crossws`. It also enhances developer experience with features like automatic port finding (via `get-port-please`), displaying QR codes for public URLs (with `unjs/uqr`), local server tunneling (using `unjs/untun`), clipboard integration for URLs, and simplified HTTPS setup with self-signed certificates. listhen aims to provide a comprehensive, zero-configuration development server experience, abstracting away common setup complexities.","status":"active","version":"1.9.1","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/listhen","tags":["javascript","typescript"],"install":[{"cmd":"npm install listhen","lang":"bash","label":"npm"},{"cmd":"yarn add listhen","lang":"bash","label":"yarn"},{"cmd":"pnpm add listhen","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { listen } = require('listhen')","symbol":"listen","correct":"import { listen } from 'listhen'"},{"note":"This is a named export, not a default export. Use for development servers that require file watching and hot reloading capabilities.","wrong":"import listenAndWatch from 'listhen'","symbol":"listenAndWatch","correct":"import { listenAndWatch } from 'listhen'"},{"note":"When importing types in TypeScript, use `import type` to ensure the import is stripped from the compiled JavaScript, preventing unnecessary runtime dependencies.","wrong":"import { Listener } from 'listhen'","symbol":"Listener","correct":"import type { Listener } from 'listhen'"}],"quickstart":{"code":"import { createApp, eventHandler } from \"h3\";\nimport { listen } from \"listhen\";\n\nconst app = createApp();\n\napp.use(\n  \"/\",\n  eventHandler(() => \"Hello world from listhen and h3!\")\n);\n\nasync function startServer() {\n  const listener = await listen(app, {\n    port: process.env.PORT ? parseInt(process.env.PORT) : 3000, // Use process.env.PORT or fallback to 3000\n    hostname: process.env.HOST || \"0.0.0.0\",\n    clipboard: true, // Copy URL to clipboard in dev\n    open: true,      // Open in browser in dev\n    showURL: true,   // Show URL in console\n    https: false     // Set to true for self-signed HTTPS in dev\n  });\n  console.log(`Server listening on ${listener.url}`);\n\n  // Graceful shutdown on common signals\n  process.on('SIGINT', () => { listener.close(); console.log('Server gracefully shutting down...'); });\n  process.on('SIGTERM', () => { listener.close(); console.log('Server gracefully shutting down...'); });\n}\n\nstartServer();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For development, accept the browser warning. For production or trusted environments, provide your own trusted SSL certificates using the `https: { cert, key }` option.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `hostname: 'localhost'` or `hostname: '127.0.0.1'` in your `listhen` options to restrict access to the local machine.","message":"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'`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Another process is currently using the specified port (e.g., 3000).","error":"Address already in use :::3000"},{"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.","cause":"Attempting to use `require()` to import an ES Module package (or a package configured primarily for ESM) in a CommonJS context.","error":"ERR_REQUIRE_ESM: require() of ES Module ... Not supported."},{"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' } }`.","cause":"You are using `https: true` with a self-signed certificate, which browsers do not inherently trust.","error":"Error: Certificate is not trusted"}],"ecosystem":"npm"}