devdomain

localhost:5173  →  my-project.test

Stop memorizing port numbers.
Give your dev server a clean .test domain with zero config.

       

Quick Start  •  CLI  •  Vite Plugin  •  API  •  How It Works

$ npx devdomain vite

devdomain v1.1.5

Domain:    my-project.test
Port:      7421
URL:       http://my-project.test:7421
Internal:  http://127.0.0.1:7421

Press Ctrl+C to stop

Before		After
http://localhost:5173	→	http://my-project.test
http://localhost:3000	→	https://dashboard.test
http://localhost:8080	→	https://api.test

Why devdomain?

	Problem	Solution
Memorable	localhost:5173 is forgettable	dashboard.test is not
Realistic	Cookies, CORS, OAuth break on localhost	.test domains behave like production
No conflicts	Port 3000 is already in use...	devdomain picks a free port automatically
Team-friendly	"What port are you on?"	Same domain for everyone
Clean URLs	http://localhost:8080/api/v2	http://api.test/v2
Trusted HTTPS	Self-signed cert warnings	One flag for a green lock via mkcert

Install

npm install -D devdomain

Quick Start

CLI (works with any dev server)

# Auto-detects your dev server (runs `npm run dev`)
npx devdomain dev

# Or specify the framework directly
npx devdomain vite
npx devdomain next
npx devdomain nuxt

# Custom domain
npx devdomain dev --domain dashboard.test

# Disable features (all enabled by default)
npx devdomain dev --no-https        # disable HTTPS
npx devdomain dev --no-clean        # keep port in URL
npx devdomain dev --no-open         # don't open browser

Vite Plugin (zero config)

// vite.config.ts
import { defineConfig } from 'vite'
import devdomain from 'devdomain/vite'

export default defineConfig({
  plugins: [
    devdomain()
  ]
})

Then just run npm run dev as usual. devdomain handles everything.

Programmatic API

import devdomain from 'devdomain'

const server = await devdomain({
  command: 'vite',
  https: true,
  clean: true,
})

console.log(server.url)    // https://my-project.test
console.log(server.port)   // 7421

// When you're done
await server.stop()

Modes

Simple Mode default npx devdomain dev http://my-project.test:7421 Maps to a .test domain with the port visible. No extra privileges beyond the hosts file edit.

Clean Mode npx devdomain dev --clean --https https://my-project.test Reverse proxy on port 80/443 - no port in the URL. Trusted green lock with --https.

CLI Reference

devdomain dev [command...]

Start your dev server with a .test domain. You can also pass the framework name directly — devdomain next is equivalent to devdomain dev next.

devdomain dev                # runs `npm run dev`
devdomain vite               # runs `npx vite`
devdomain next               # runs `npx next dev`
devdomain dev next            # same as above

Flags:

Flag	Default	Description
-d, --domain <name>	auto-detected	Custom domain (e.g. dashboard.test)
--no-https	HTTPS on	Disable trusted HTTPS
--no-clean	Clean on	Show port in URL (skip reverse proxy)
--no-open	Open on	Don't auto-open browser
--port-range <range>	4000-8999	Custom port range (e.g. 5000-9000)

Note: HTTPS, clean URLs, and auto-open are enabled by default. Use the --no-* flags to disable them.

Duplicate domain: If the domain is already proxied by a previous session, devdomain will ask whether to replace or cancel.

devdomain status

Show all active processes, Herd/Valet proxies, and host entries.

devdomain kill <port|pid|domain>

Kill a process and clean up its proxy. Accepts a port number, PID, or domain name.

devdomain kill 4609
devdomain kill vite-test.test

devdomain kill-all

Kill all devdomain processes and remove all proxies/domains.

devdomain setup

Install mkcert's local CA. Run this once before using HTTPS.

devdomain list

Show all active devdomain domains in your hosts file.

devdomain cleanup

Remove all devdomain entries from your hosts file.

Vite Plugin Options

devdomain({
  domain: 'my-app.test',  // auto-detected from package.json if omitted
  https: true,             // trusted HTTPS with mkcert
  clean: true,             // reverse proxy on port 80/443
  open: true,              // open browser on start
})

Programmatic API

const result = await devdomain(options)

Options:

Option	Type	Default	Description
domain	string	auto-detected	Domain name (e.g. my-app.test)
https	boolean	true	Trusted HTTPS via mkcert
clean	boolean	true	Reverse proxy for clean URLs
command	string	-	Dev server command to spawn
args	string[]	[]	Arguments for the command
portRange	[number, number]	[4000, 8999]	Port range
open	boolean	true	Auto-open browser
cwd	string	process.cwd()	Working directory
onConflict	(conflict) => 'replace' | 'cancel'	replaces silently	Called when domain is already in use

Returns:

{
  domain: string       // 'my-project.test'
  port: number         // 7421
  url: string          // 'https://my-project.test'
  internalUrl: string  // 'http://127.0.0.1:7421'
  stop: () => Promise<void>
}

How It Works

• Detects your project name from package.json or the folder name
• Finds a free port randomly in the 4000-8999 range
• Adds a hosts entry (127.0.0.1 my-project.test # devdomain) - prompts for sudo once
• (Optional) Generates a trusted TLS certificate with mkcert
• (Optional) Starts a reverse proxy on port 80/443 for clean URLs
• Spawns your dev server on the chosen port
• Cleans up the hosts entry on exit

All hosts entries are tagged with # devdomain so they're easy to identify and clean up.

Requirements

• Node.js >= 18
• mkcert (only for --https) - install via brew install mkcert / apt install mkcert / choco install mkcert
• sudo access for editing /etc/hosts (one-time prompt)

.test Domain

devdomain uses .test domains as defined in RFC 6761. These are officially reserved for local development and testing - they will never conflict with real websites.

devdomain — because your dev server deserves a real name.

MIT License