{"_id":"@abdullahharunozturk/localtld","_rev":"3-a995668ed6ea4df962a889450cf85b53","name":"@abdullahharunozturk/localtld","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@abdullahharunozturk/localtld","version":"0.1.0","keywords":["localhost","dns","dnsmasq","caddy","reverse-proxy","dev","devtools","domain","tld","dx","local-development"],"author":{"name":"Abdullah Harun Öztürk"},"license":"MIT","_id":"@abdullahharunozturk/localtld@0.1.0","maintainers":[{"name":"abdullahharunozturk","email":"ozturkabdu@itu.edu.tr"}],"homepage":"https://localtld.sh","bugs":{"url":"https://github.com/abdullahharunozturk/localtld/issues"},"os":["darwin"],"bin":{"localtld":"bin/localtld"},"dist":{"shasum":"c84f5b0333892fd2b429d885f2d8755b2435d0ba","tarball":"https://registry.npmjs.org/@abdullahharunozturk/localtld/-/localtld-0.1.0.tgz","fileCount":5,"integrity":"sha512-HAND7mftleaf5hRKOf/Q5UinucbKhBrfvcWCaGl74MFez2gzkY7T8fI5ETEmHxWwIe33V9thWiu4R1PVi6FlKQ==","signatures":[{"sig":"MEYCIQDHPrDdJnC21KA0Dq9x6nTlUH8a5eCPZconeUYlTCSuYgIhANH5anVIxfJD5sRxDxmiaE6ICKpHakcLE7Ov04BDWOd5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23526},"gitHead":"a9290c8f06e67e8aa2accb9e3958556c58e3162b","_npmUser":{"name":"abdullahharunozturk","email":"ozturkabdu@itu.edu.tr"},"repository":{"url":"git+https://github.com/abdullahharunozturk/localtld.git","type":"git"},"_npmVersion":"11.10.0","description":"Give your local projects real domains on dynamic ports — access panel.aaron.localtld instead of chasing ports.","directories":{},"_nodeVersion":"22.21.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/localtld_0.1.0_1784050140509_0.3878506566124562","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@abdullahharunozturk/localtld","version":"0.1.1","keywords":["localhost","dns","dnsmasq","caddy","reverse-proxy","dev","devtools","domain","tld","dx","local-development"],"author":{"name":"Abdullah Harun Öztürk"},"license":"MIT","_id":"@abdullahharunozturk/localtld@0.1.1","maintainers":[{"name":"abdullahharunozturk","email":"ozturkabdu@itu.edu.tr"}],"homepage":"https://localtld.sh","bugs":{"url":"https://github.com/abdullahharunozturk/localtld/issues"},"os":["darwin"],"bin":{"localtld":"bin/localtld"},"dist":{"shasum":"2411008b8467d74b1f5f70445697b864693baabf","tarball":"https://registry.npmjs.org/@abdullahharunozturk/localtld/-/localtld-0.1.1.tgz","fileCount":5,"integrity":"sha512-PVC1a0ZZ0J3+fRmieRiCZU1ByD5VyZoFI8lB/cHEC6ZvwGbOGYZagCMOgMngqz1hIDYZsZA57RUnU574sHoznw==","signatures":[{"sig":"MEYCIQCm6jvbPiaAxsI93XD8jXjvXAMY29S2jrCSmlFq9cHpWQIhAJ8ZYLWpS8DuG4HBnVjRUpdKz4i2HaRPJ0I99dfqYH9T","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@abdullahharunozturk%2flocaltld@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":22496},"gitHead":"391ec9fc3c966fd11a7c187dc6d73ce1627352f9","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:04ce2b8e-db1a-462b-aa5d-fe1d28167266"}},"repository":{"url":"git+https://github.com/abdullahharunozturk/localtld.git","type":"git"},"_npmVersion":"12.0.1","description":"Give your local projects real domains on dynamic ports — access panel.aaron.localtld instead of chasing ports.","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/localtld_0.1.1_1784952653212_0.6005915675690348","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@abdullahharunozturk/localtld","version":"0.1.2","publishConfig":{"access":"public"},"description":"Give your local projects real domains on dynamic ports — access panel.aaron.localtld instead of chasing ports.","bin":{"localtld":"bin/localtld"},"os":["darwin"],"keywords":["localhost","dns","dnsmasq","caddy","reverse-proxy","dev","devtools","domain","tld","dx","local-development"],"homepage":"https://localtld.sh","repository":{"type":"git","url":"git+https://github.com/abdullahharunozturk/localtld.git"},"bugs":{"url":"https://github.com/abdullahharunozturk/localtld/issues"},"author":{"name":"Abdullah Harun Öztürk"},"license":"MIT","gitHead":"2d76bc404cf4f049faf19de14dd112dd4e0d9ec3","_id":"@abdullahharunozturk/localtld@0.1.2","_nodeVersion":"22.23.1","_npmVersion":"12.0.1","dist":{"integrity":"sha512-Tc+mfrqc6XqxorXf8To8WZOtAUKy5tuzA8Enx5/dv5QR2hOSdfK4Fi4bGY+sTXexmhKGBILfWlxuU1DulazKdA==","shasum":"de77f0f148e22c3a33aaa5f085557a70bf09d7bb","tarball":"https://registry.npmjs.org/@abdullahharunozturk/localtld/-/localtld-0.1.2.tgz","fileCount":5,"unpackedSize":22928,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@abdullahharunozturk%2flocaltld@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCd+lIlidwZQUinurNf94F4pqAlwHOWSMXUnVtBwUfgUQIhAPNgUe4MGREUyGLr6TN3CnxwAcIum8UFvauQGzFQolQX"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:04ce2b8e-db1a-462b-aa5d-fe1d28167266"}},"directories":{},"maintainers":[{"name":"abdullahharunozturk","email":"ozturkabdu@itu.edu.tr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/localtld_0.1.2_1784953229635_0.21959259387455576"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-14T17:29:00.276Z","modified":"2026-07-25T04:20:30.107Z","0.1.0":"2026-07-14T17:29:00.671Z","0.1.1":"2026-07-25T04:10:53.359Z","0.1.2":"2026-07-25T04:20:29.819Z"},"bugs":{"url":"https://github.com/abdullahharunozturk/localtld/issues"},"author":{"name":"Abdullah Harun Öztürk"},"license":"MIT","homepage":"https://localtld.sh","keywords":["localhost","dns","dnsmasq","caddy","reverse-proxy","dev","devtools","domain","tld","dx","local-development"],"repository":{"type":"git","url":"git+https://github.com/abdullahharunozturk/localtld.git"},"description":"Give your local projects real domains on dynamic ports — access panel.aaron.localtld instead of chasing ports.","maintainers":[{"name":"abdullahharunozturk","email":"ozturkabdu@itu.edu.tr"}],"readme":"# localtld\n\n**Give your local projects real domains on dynamic ports.** Stop chasing ports — reach your app at `panel.aaron.localtld`.\n\n```jsonc\n// package.json\n{ \"localtld\": \"panel.aaron\" }\n```\n\n```bash\nlocaltld run -- pnpm dev\n#   → http://panel.aaron.localtld   (dynamic port — you never need to know it)\n```\n\nWhatever port your dev server grabs (3000, 51234, doesn't matter), you always reach it at the same clean domain. Run hundreds of projects at once: no port collisions, nothing to track.\n\n## Zero-config, even if you've never heard of localtld\n\nWire it once in a project and it *just works* on any machine that has localtld set up — the developer doesn't need to know localtld exists:\n\n```jsonc\n// package.json\n{\n  \"localtld\": \"panel.aaron\",\n  \"scripts\": {\n    \"dev\": \"if command -v localtld >/dev/null 2>&1; then localtld run -- next dev; else next dev; fi\"\n  },\n  \"optionalDependencies\": {\n    \"@abdullahharunozturk/localtld\": \"^0.1.0\"\n  }\n}\n```\n\nNow the normal workflow does everything:\n\n```bash\npnpm install     # on macOS the localtld binary lands in node_modules/.bin\npnpm dev\n```\n\n**Why `optionalDependencies` + the guard, not a plain `devDependencies` entry:**\n\n- localtld is macOS-only (`\"os\": [\"darwin\"]`). As an *optional* dependency, Linux/Windows/CI **skip it silently** — a regular `dependencies`/`devDependencies` entry would fail the whole install with `EBADPLATFORM`.\n- The `command -v` guard lets the `dev` script survive on any machine where the binary isn't present (non-macOS, or one that skipped it).\n\nResult — zero action required from your teammates, and nobody needs to know localtld exists:\n\n| Machine | `pnpm install` | `pnpm dev` |\n|---------|----------------|------------|\n| macOS, set up | installs localtld | `panel.aaron.localtld` |\n| macOS, not set up | installs localtld | offers `localtld setup`, else `localhost` |\n| Linux / Windows / CI | skips it (no error) | plain `next dev` on `localhost` |\n\n### Without adding a dependency\n\nDon't want localtld in your `devDependencies` (or it isn't installed on every machine)? Guard the script so it degrades to a plain run when the binary is absent:\n\n```jsonc\n// package.json\n{\n  \"localtld\": \"panel.aaron\",\n  \"scripts\": {\n    \"dev\": \"if command -v localtld >/dev/null 2>&1; then localtld run -- next dev; else next dev; fi\"\n  }\n}\n```\n\n- Machine **has** the `localtld` binary → pretty domain.\n- Machine **doesn't** → plain `next dev` (`localhost:PORT`), no error, zero dependency.\n\n`command -v` is POSIX `sh` (macOS/Linux). Use this when you want the repo to carry **zero** localtld dependency — no `devDependencies` entry, no assumption that any teammate has it installed. (Prefer the pinned `devDependencies` approach above if you'd rather everyone get the same domain automatically.)\n\n## How it works\n\nlocaltld doesn't reinvent anything; it orchestrates two standard tools:\n\n```\nbrowser → panel.aaron.localtld\n   │  dnsmasq:  *.localtld → 127.0.0.1        (+ macOS /etc/resolver)\n   ▼\n127.0.0.1:80 → Caddy  (Host header → the right port)\n   ▼\n127.0.0.1:51234 ← your dev server (localtld assigned it via PORT env)\n```\n\n- **TLD is fixed** (`.localtld`) — identical on every machine, so shared configs, docs and bug reports always match.\n- **Label is a project-level setting** (`package.json`) — one line, no TLD in it, so the repo stays portable.\n- **Opt-in & graceful**: without a system setup, projects just run on `localhost:PORT`.\n\n## Environment variables (`.env`)\n\nlocaltld changes the *host* your dev server is reachable at — it doesn't touch your app config. When services talk to each other by URL (a frontend calling an API, CORS origins, …), those URLs differ between the two worlds:\n\n- **localtld ON** → `http://core.aaron.localtld` (port 80, via Caddy)\n- **localtld OFF** → `http://localhost:3001`\n\n`.env` files are static and `${VAR}` expansion isn't portable across tools, so the simplest pattern is to ship both and let each machine pick. Default to `localhost` in code so the project runs with zero config:\n\n```dotenv\n# .env.example\n\n# localtld OFF (default):\nCORE_API_URL=http://localhost:3001/api\n# localtld ON:\n# CORE_API_URL=http://core.aaron.localtld/api\n```\n\n```ts\n// default to localhost → works even without localtld\nconst base = process.env.CORE_API_URL ?? 'http://localhost:3001/api';\n```\n\nA teammate copies `.env.example` → `.env`; if they use localtld, they swap the commented line. Keep the URL in `.env` (or the `.env.example` comment) rather than hardcoded in source — not every machine runs localtld, and the `localhost` fallback needs to keep working.\n\n## Install\n\n```bash\n# Homebrew (primary)\nbrew install abdullahharunozturk/localtld/localtld\n\n# or npm (CLI is still `localtld`)\nnpm install -g @abdullahharunozturk/localtld\n\n# or curl (coming soon — needs localtld.sh to be live)\n# curl -fsSL https://localtld.sh | bash\n\nlocaltld setup               # configure dnsmasq + Caddy (asks for sudo)\n```\n\nRequires macOS + Homebrew. Brew pulls in `caddy`, `dnsmasq`, and `jq` automatically; via npm/curl, `setup` installs them if missing.\n\n## Commands\n\n| Command | What it does |\n|---------|--------------|\n| `localtld setup` | First-time setup: configure dnsmasq/Caddy |\n| `localtld run -- <cmd>` | Run a project under its domain (falls back if not set up) |\n| `localtld list` | Show active projects and their domains |\n| `localtld doctor` | Check the health of your setup |\n| `localtld uninstall` | Revert DNS/route changes |\n\n## Why `.localtld` is fixed\n\nEvery project gets `<label>.localtld` — the suffix is deliberately **not** configurable. One standard suffix means a shared `package.json` entry, a doc snippet or a bug report works identically on every machine, and `.localtld` is not a real TLD so it can never collide with a live website.\n\nWant a different suffix? Fork and edit the single `TLD=` line at the top of `bin/localtld`. A built-in guard refuses forks that set a **real** TLD (`.com`, `.dev`, …), since every site under it would resolve to `127.0.0.1` on the user's machine.\n\n> Upgrading from an older version with a custom TLD? It is no longer read — the tool\n> warns once and uses `.localtld`; run `localtld setup` again to re-wire DNS.\n\n## License\n\nMIT © Abdullah Harun Öztürk\n","readmeFilename":"README.md"}