$ 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

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

1. Detects your project name from package.json or the folder name
2. Finds a free port randomly in the 4000-8999 range
3. Adds a hosts entry (127.0.0.1 my-project.test # devdomain) - prompts for sudo once
4. (Optional) Generates a trusted TLS certificate with mkcert
5. (Optional) Starts a reverse proxy on port 80/443 for clean URLs
6. Spawns your dev server on the chosen port
7. 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.