{"id":13902731,"url":"https://github.com/unjs/listhen","last_synced_at":"2025-06-10T22:41:52.573Z","repository":{"id":37020545,"uuid":"318630370","full_name":"unjs/listhen","owner":"unjs","description":"👂 Elegant HTTP Listener ","archived":false,"fork":false,"pushed_at":"2024-05-27T10:19:24.000Z","size":1418,"stargazers_count":389,"open_issues_count":21,"forks_count":28,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-29T11:38:34.203Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-04T20:41:16.000Z","updated_at":"2024-06-01T00:27:12.379Z","dependencies_parsed_at":"2023-12-05T23:25:44.913Z","dependency_job_id":"f79b0112-47dc-4f17-928b-d62f275f83d6","html_url":"https://github.com/unjs/listhen","commit_stats":{"total_commits":143,"total_committers":16,"mean_commits":8.9375,"dds":0.6083916083916083,"last_synced_commit":"9d08f0044f5bd8ec4905d43a15cc069387c7ab9f"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Flisthen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Flisthen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Flisthen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unjs%2Flisthen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unjs","download_url":"https://codeload.github.com/unjs/listhen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226310656,"owners_count":17604619,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T22:01:21.181Z","updated_at":"2024-11-25T10:32:25.189Z","avatar_url":"https://github.com/unjs.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","others"],"sub_categories":[],"readme":"# 👂 listhen\n\n\u003c!-- automd:badges --\u003e\n\n[![npm version](https://img.shields.io/npm/v/listhen)](https://npmjs.com/package/listhen)\n[![npm downloads](https://img.shields.io/npm/dm/listhen)](https://npmjs.com/package/listhen)\n\n\u003c!-- /automd --\u003e\n\nElegant HTTP listener!\n\n[👉 Online Playground](https://stackblitz.com/github/unjs/listhen/tree/main/playground?startScript=dev)\n\n## Features\n\n✅ Dev server with HMR, static, WebSockets and TypeScript support with \u003ca href=\"https://github.com/unjs/jiti\"\u003eunjs/jiti\u003c/a\u003e\u003cbr\u003e\n\n✅ Works with Node.js, Express, and \u003ca href=\"https://github.com/unjs/h3\"\u003eunjs/h3\u003c/a\u003e out of the box \u003cbr\u003e\n\n✅ Show the QR code of the public URL with \u003ca href=\"https://github.com/unjs/uqr\"\u003eunjs/uqr\u003c/a\u003e\u003cbr\u003e\n\n✅ Tunnel your local server to the world with \u003ca href=\"https://github.com/unjs/untun\"\u003eunjs/untun\u003c/a\u003e\u003cbr\u003e\n\n✅ Assign a port or fallback to a nicer alternative with \u003ca href=\"https://github.com/unjs/get-port-please\"\u003eunjs/get-port-please\u003c/a\u003e\n\n✅ Gracefully shutdown Server with \u003ca href=\"https://github.com/thedillonb/http-shutdown\"\u003ehttp-shutdown\u003c/a\u003e\u003cbr\u003e\n\n✅ Zero Config WebSockets with \u003ca href=\"https://github.com/unjs/crossws\"\u003eunjs/crossws\u003c/a\u003e\n\n✅ Copy the URL to the clipboard\u003cbr\u003e\n\n✅ HTTPS support with self-signed certificates\u003cbr\u003e\n\n✅ Open URL in browser\u003cbr\u003e\n\n✅ Detect test and production environments to auto-adjust behavior\u003cbr\u003e\n\n✅ Close on the exit signal\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg width=\"100%\" src=\"./.assets/screenshot.png\"\u003e\n\u003c/div\u003e\n\n## Quick Usage (CLI)\n\nYou can run your applications in localhost with TypeScript support and watch mode using `listhen` CLI:\n\nCreate `index.ts`:\n\n```ts\nexport default (req, res) =\u003e {\n  res.end(\"Hello World!\");\n};\n```\n\nor using [unjs/h3](https://github.com/unjs/h3):\n\n```ts\nimport { createApp, eventHandler } from \"h3\";\n\nexport const app = createApp();\n\napp.use(\n  \"/\",\n  eventHandler(() =\u003e \"Hello world!\"),\n);\n```\n\nor use npx to invoke `listhen` command:\n\n```sh\nnpx listhen -w ./index.ts\n```\n\n## Usage (API)\n\nInstall package:\n\n```bash\n# pnpm\npnpm i listhen\n\n# npm\nnpm i listhen\n\n# yarn\nyarn add listhen\n\n```\n\nImport into your Node.js project:\n\n```js\n// CommonJS\nconst { listen, listenAndWatch } = require(\"listhen\");\n\n// ESM\nimport { listen, listenAndWatch } from \"listhen\";\n```\n\n```ts\nconst handler = (req, res) =\u003e {\n  res.end(\"Hi!\")\n}\n\n// listener: { url, getURL, server, close, ... }\nconst listener = await listen(handler, options)\n```\n\n## Options\n\n### `port`\n\n- Default: `process.env.PORT` or 3000 or memorized random (see [get-port-please](https://github.com/unjs/get-port-please))\n\nPort to listen.\n\n### `hostname`\n\n- Default: `process.env.HOST || '0.0.0.0'`\n\nDefault hostname to listen.\n\n### `https`\n\n- Type: Boolean | Object\n- Default: `false`\n\nListen on HTTPS with SSL enabled.\n\n#### Self-Signed Certificate\n\nBy setting `https: true`, listhen will use an auto-generated self-signed certificate.\n\nYou can set https to an object for custom options. Possible options:\n\n- `domains`: (Array) Default is `['localhost', '127.0.0.1', '::1']`.\n- `validityDays`: (Number) Default is `1`.\n\n#### User-Provided Certificate\n\nSet `https: { cert, key }` where the cert and key are paths to the SSL certificates.\nWith an encrypted private key, you also need to set `passphrase` on the `https` object.\n\nTo provide a certificate stored in a keystore set `https: { pfx }` with a path to the keystore.\nWhen the keystore is password protected also set `passphrase`.\n\nYou can also provide an inline cert and key instead of reading from the filesystem. In this case, they should start with `--`.\n\n### `showURL`\n\n- Default: `true` (force disabled on a test environment)\n\nShow a CLI message for the listening URL.\n\n### `baseURL`\n\n- Default: `/`\n\n### `open`\n\n- Default: `false` (force disabled on test and production environments)\n\nOpen the URL in the browser. Silently ignores errors.\n\n### `clipboard`\n\n- Default: `false` (force disabled on test and production environments)\n\nCopy the URL to the clipboard. Silently ignores errors.\n\n### `isTest`\n\n- Default: `process.env.NODE_ENV === 'test'`\n\nDetect if running in a test environment to disable some features.\n\n### `autoClose`\n\n- Default: `true`\n\nAutomatically close when an `exit` event, `SIGTERM`, `SIGINT` or `SIGHUP` signal is received in the process.\n\n### `publicURL`\n\n- Default: (the first public URL listening)\n\nThe public URL to show in the CLI output\n\n### `qr`\n\n- Default: `true`\n\nPrint QR Code for public address.\n\n### `public`\n\n- Default: `false` for development or when `hostname` is `localhost` and `true` for production\n\nWhen enabled, listhen tries to listen to all network interfaces. You can also enable this option using `--host` CLI flag.\n\n### `ws`\n\n- Default: `false`\n\nEnable experimental WebSocket support using [unjs/crossws](https://crossws.unjs.io/) or node upgrade handler.\n\nOption can be a function for Node.js `upgrade` handler (`(req, head) =\u003e void`) or an Object to use [CrossWS Hooks](https://crossws.unjs.io/guide/api).\n\nWhen using dev server CLI, you can easily use `--ws` and a named export called `websocket` to define [CrossWS Hooks](https://github.com/unjs/crossws) with HMR support!\n\n## License\n\n\u003c!-- automd:contributors license=MIT author=\"pi0\" --\u003e\n\nPublished under the [MIT](https://github.com/unjs/listhen/blob/main/LICENSE) license.\nMade by [@pi0](https://github.com/pi0) and [community](https://github.com/unjs/listhen/graphs/contributors) 💛\n\u003cbr\u003e\u003cbr\u003e\n\u003ca href=\"https://github.com/unjs/listhen/graphs/contributors\"\u003e\n\u003cimg src=\"https://contrib.rocks/image?repo=unjs/listhen\" /\u003e\n\u003c/a\u003e\n\n\u003c!-- /automd --\u003e\n\n\u003c!-- automd:with-automd --\u003e\n\n---\n\n_🤖 auto updated with [automd](https://automd.unjs.io)_\n\n\u003c!-- /automd --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Flisthen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funjs%2Flisthen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funjs%2Flisthen/lists"}