{"id":20450156,"url":"https://github.com/kishanbagaria/localhost-mapper","last_synced_at":"2025-04-13T02:12:53.732Z","repository":{"id":55851779,"uuid":"125551413","full_name":"KishanBagaria/localhost-mapper","owner":"KishanBagaria","description":"🔗 Run your dev servers on addresses like https://awesome-site/ or https://🍔/ instead of localhost","archived":false,"fork":false,"pushed_at":"2021-02-28T12:29:44.000Z","size":590,"stargazers_count":85,"open_issues_count":7,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T02:12:48.549Z","etag":null,"topics":["cli-app","domains","http-proxy","js-library","localhost","network","pac","proxy","proxy-auto-config"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KishanBagaria.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-16T17:53:00.000Z","updated_at":"2025-04-11T17:01:20.000Z","dependencies_parsed_at":"2022-08-15T07:50:52.979Z","dependency_job_id":null,"html_url":"https://github.com/KishanBagaria/localhost-mapper","commit_stats":null,"previous_names":["kishanbagaria/frwrd"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KishanBagaria%2Flocalhost-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KishanBagaria%2Flocalhost-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KishanBagaria%2Flocalhost-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KishanBagaria%2Flocalhost-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KishanBagaria","download_url":"https://codeload.github.com/KishanBagaria/localhost-mapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654094,"owners_count":21140236,"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":["cli-app","domains","http-proxy","js-library","localhost","network","pac","proxy","proxy-auto-config"],"created_at":"2024-11-15T10:50:56.391Z","updated_at":"2025-04-13T02:12:53.713Z","avatar_url":"https://github.com/KishanBagaria.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![localhost-mapper](media/banner.png)\n\n🔗 Run your dev servers on addresses like `https://awesome-site/` or `https://🍔/`\u003csup\u003e[1](#fn1)\u003c/sup\u003e instead of ugly addresses like `http://localhost:1337`\n\n\u003cimg src=\"media/example.png\" alt=\"localhost-mapper Example\" width=\"800\" /\u003e\n\nYou can run your localhost servers on practically any address like:  \n`http://cat.meow/`  \n`http://🍎🦄.👩‍💻/`\u003csup\u003e[1](#fn1)\u003c/sup\u003e  \n`https://my.awesome.site/` ([HTTPS](#newAddress) will automatically be supported even if your original server listens only on HTTP)\n\nWorks on macOS and Windows, and [Linux with some manual config](#linux).\n\n## Install\n\n```sh\n$ yarn add --dev localhost-mapper\n```\nor\n```sh\n$ npm i --dev localhost-mapper\n```\n\n## Usage\n\nImport the module and use it like:\n```js\nimport lhMapper from 'localhost-mapper'\n// or const lhMapper = require('localhost-mapper')\n\n// [...] your server code here [...]\n\nconst { PORT = 31415 } = process.env\nlhMapper.map(`http://localhost:${PORT}`, 'http://awesome-site')\n  .then(() =\u003e console.log('listening on http://awesome-site'))\n\n// now open http://awesome-site in a browser\n```\n\nor type in the following in a terminal:\n```sh\n$ lh-map http://localhost:31415 http://awesome-site\n```\n\n## How It Works\n\nlocalhost-mapper works by creating a [Proxy Auto-Config (PAC)](https://en.wikipedia.org/wiki/Proxy_auto-config) file and automatically changing the PAC URL setting on Windows and macOS. The original setting is restored when localhost-mapper isn't being used.\n\n\u003ca name=\"linux\"\u003e\u003c/a\u003e\nIt's incompatible with [cURL][curl-pac] and Wget since they don't support PAC files. Also, automatic changing of the PAC URL hasn't been implemented for Linux, so you'll have to manually set the PAC URL for your browser or OS.\n\n### Why not simply edit the `/etc/hosts` file?\n\nThe `hosts` file cannot map to different ports. So you can map `http://localhost:1337` → `http://unicorns:1337` easily but not `http://localhost:1337` → `http://unicorns` without listening on port 80. Listening on port 80 requires sudo.\n\nSince you can only get one server to listen on port 80, the `hosts` file is limited to just a single mapping. With localhost-mapper, you can map as many hosts as you want simultaneously (`http://localhost:31415` → `https://alice`, `http://localhost:1234` → `http://bob`).\n\nManually editing the `hosts` file is a lot of work, compared to localhost-mapper which can be used by just adding a line of code that you can forget about. localhost-mapper will only be active when you run code that imports it. It'll restore all filesystem/network changes when it's not being used.\n\nWhen you share your code, other people will have to manually edit the `hosts` file on their environment, but with localhost-mapper they can start using the prettified domain out of the box as soon as they run the code.\n\n## API\n\n#### `localhostMapper.map(originalAddress: String, newAddress: String|Array\u003cString\u003e|RegExp, [options: Object]): Promise\u003cvoid\u003e`\n\nForwards `originalAddress` to `newAddress` (`http://localhost:1337` → `http://cat.meow`). Aliased as `localhostMapper.add`.\n\n##### `originalAddress: String`\n\nThe original address to be proxied/forwarded to `newAddress`. Like `http://localhost:1337`.\n\n\u003ca name=\"newAddress\"\u003e\u003c/a\u003e\n##### `newAddress: String|Array\u003cString\u003e|RegExp`\n\nThe new address to listen on. Like `http://awesome-site`. Pass in an array of strings to listen on multiple addresses in one call. Also supports regex, like `/http\\:\\/\\/.*everything\\.awesome/`\n\nIf this starts with `https:`, self-signed certificates will be generated and a HTTPS server will be created that proxies `originalAddress`. So HTTPS will work even if `originalAddress` listens only on HTTP. To use your own certs, check out the `ssl` option below.\nIf you pass in a `RegExp` that matches HTTPS domains, you must set `ssl` to `true` to use automatically generate and use self-signed certificates.\n\n##### `options: Object`\n\n```js\n{\n  proxy: Boolean,\n  proxyConfig: Object,\n  ssl: {\n    key: String,\n    cert: String\n  }\n}\n```\n\n###### `proxy: Boolean`\n\nBy default, localhost-mapper proxies the contents of `originalAddress` so that the `Host` header is unchanged. This makes sure it is compatible with codebases that it wouldn't otherwise be without requiring changes. Setting this to `false` will disable proxying.\n\n###### `proxyConfig: Object`\n\nPassed as-is to [http-proxy](http-proxy). Only applicable when `proxy` is not `false`.\n\n###### `ssl: { key: String, cert: String }`\n\nContents of key/cert file to use for HTTPS. Set this to `true` to automatically generate and use self-signed certificates.\n\n#### `localhostMapper.unmap(newAddress: String|Array\u003cString\u003e|RegExp): Promise\u003cvoid\u003e`\n\nUndos the `localhostMapper.map(...)` call, i.e. stops listening for `newAddress`. All addresses will automatically be removed when the node process exits. Aliased as `localhostMapper.remove`.\n\n---\n\n\u003ca name=\"fn1\"\u003e[1]\u003c/a\u003e: While all browsers support emoji domains, not all show the actual emoji in the address bar. Safari will show the emoji like you'd want it to, while Chrome and Firefox will show the Punycode version: `http://xn--ui8h/`\n\n## Acknowledgements\n\n* [winproxy](https://github.com/getlantern/winproxy) for the executable to change PAC URL automatically in Windows (licensed under [Apache-2.0](https://github.com/getlantern/winproxy/blob/master/LICENSE))\n* [hotel](https://github.com/typicode/hotel) for the inspiration\n\n## License\n\nMIT © [Kishan Bagaria](https://kishanbagaria.com)\n\n[curl-pac]: https://curl.haxx.se/docs/faq.html#Does_curl_support_Javascript_or\n[http-proxy]: https://www.npmjs.com/package/http-proxy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkishanbagaria%2Flocalhost-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkishanbagaria%2Flocalhost-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkishanbagaria%2Flocalhost-mapper/lists"}