@hamedb89/localghost

Buh. Friendly local hostnames for app repos.

Localghost is a tiny Node.js CLI for clean local app domains. Add it as a dev dependency, keep running the command your team already knows, and use http://app.localhost/ instead of remembering which port belongs to which process.

Website · Docs · npm · GitHub

Quick Start

yarn add -D @hamedb89/localghost

For Vite apps, add the plugin once:

import { defineConfig } from "vite";
import { localGhostPlugin } from "@hamedb89/localghost/vite";

export default defineConfig({
  plugins: [localGhostPlugin()]
});

Then keep using the command your repo already expects:

yarn dev

On the first interactive run, Localghost can create .localghost, explain the /etc/hosts change, write ops/local/Caddyfile, and print the browser-facing URL:

localghost
local:  http://app.localhost/
also:   http://www.app.localhost/
target: http://127.0.0.1:5173/

For non-Vite apps, wrap your raw dev command:

{
  "scripts": {
    "dev": "localghost run -- yarn dev:raw",
    "dev:raw": "next dev"
  }
}

What It Does

• Reads .localghost from your app repo and turns hostnames into local routes.
• Updates only a managed Localghost block in /etc/hosts during explicit setup.
• Generates ops/local/Caddyfile for local reverse proxying.
• Keeps HTTP as the default; HTTPS is explicit with --https, --ssl, or config.
• Checks whether Caddy is installed, but never installs Homebrew packages for you.
• Gives Vite explicit server.allowedHosts entries without using allowedHosts: true.
• Exposes CLI, config, state, and route output for scripts and agent workflows.

Common Commands

localghost init --write-scripts
localghost doctor
localghost setup
localghost status --ready
localghost dev
localghost run -- vite
localghost routes
localghost ps
localghost reset
localghost teardown
localghost update

Prefer .localhost names. .local is supported, but Localghost warns because .local can collide with mDNS/Bonjour.

Configuration

Most apps only need a .localghost file when they want explicit hostnames or multiple services:

# Format: <host> <port>
app.localhost 5173
www.app.localhost 5173
api.app.localhost 8787

Most repos do not need localghost.config.mjs. Add it only for decisions like HTTPS, dynamic-port behavior, www. aliases, custom config files, or ghostTunnel preview domains.

Trust

• CI runs typecheck, build, site build, and npm package dry-run on Node 20 and 22.
• GitHub Pages is deployed by Actions from the checked-in site/, docs/, and assets/ sources.
• Preview the exact Pages artifact locally with npm run site:serve, then open http://127.0.0.1:4173/.
• npm publish is guarded by prepublishOnly and the release workflow publishes with npm provenance.
• Runtime dependencies are intentionally small: commander and execa. Vite is an optional peer dependency.
• No postinstall scripts, hidden Homebrew installs, surprise browser tabs, or broad hosts-file rewrites.
• Update checks are best-effort, cached for 24 hours, and can be disabled with LOCALGHOST_NO_UPDATE_CHECK=1 or --no-update-check.

Docs

The full docs are served on GitHub Pages:

• User flows
• CLI reference
• Ghost Tunnel guide
• macOS widget notes
• Brand guidelines
• All docs

API

import {
  getConfigFileCandidates,
  initLocalghost,
  readDevHosts,
  readLocalghostState,
  removeSystemHosts,
  renderCaddyfile,
  renderHostsBlock,
  runDoctor,
  updateSystemHosts
} from "@hamedb89/localghost";

import { localGhostPlugin } from "@hamedb89/localghost/vite";

License

MIT