@nice-code/devtools-vite

Docs: nicecode.io — guides, integrations, and the full API surface. Working with an AI assistant? Point it at nicecode.io/llms.txt — the complete, current docs flattened into plain text.

A Vite dev-server plugin that makes opening the nice-code devtools the entire setup.

Add it once, and the first time anyone clicks devtools the local relay starts itself. Every other client of that app — a second tab, a private window, another browser, a phone on your LAN — finds it and joins the same devtools window. No relay to run in a second terminal, no relayUrl to configure, and no console noise in the sessions that never open devtools at all.

import { niceDevtools } from "@nice-code/devtools-vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), niceDevtools()],
});

That's it. Dev-only: the plugin is apply: "serve", so a production build contains none of it.

What it actually does

It serves two same-origin routes on your dev server:

| Route | Method | Meaning | | --- | --- | --- | | /__nice_devtools/status | GET | Is a relay running? Never starts one. | | /__nice_devtools/ensure | POST | Start one if it isn't. Idempotent. |

Your app's devtools bridge asks status when it loads and joins the relay if there is one. Clicking the devtools launcher POSTs ensure. That is the whole protocol.

Why an endpoint rather than letting the browser probe the relay's port directly? The page is served from localhost:5173 and the relay lives on localhost:5199 — a cross-origin request, which would force the relay to grow CORS headers and an opinion about who may ask it questions. The dev server is already same-origin with the app, and it is the only process that can start a relay anyway.

Options

niceDevtools({
  port: 5199,              // the relay's well-known port
  host: "127.0.0.1",       // pass "0.0.0.0" for the phone-on-your-LAN workflow
  autoStart: "on-demand",  // "eager" | "never"
});

• autoStart: "on-demand" (default) — the relay starts on the first devtools click. Most dev sessions never open devtools, and they should not pay a port and a server for it.
• autoStart: "eager" — start it when the dev server boots.
• autoStart: "never" — only report whether a relay is running; you start it yourself with bunx @nice-code/devtools-relay (e.g. to pass flags this plugin doesn't expose).

One relay, many dev servers

The port is well-known because discovery needs exactly one place to look — which means two dev servers inevitably race for it. That race is resolved, not prevented:

probe → if a relay answers, use it → else bind → if the bind loses, probe again.

Losing the bind means somebody else won it in the intervening moments, so their relay is the one everyone should use. Hosting one relay per dev server would instead re-partition clients by whichever port their app happens to be served from, which is the exact split the relay exists to heal.

The relay runs in-process, inside whichever dev server started it, so it dies with that process — there is no orphan to hunt down. If that dev server exits while others are still running, surviving clients ask their dev server to stand a new one up, and reconnect to it. No page reload.

Liveness is not identity

Before concluding "a relay is already running", the plugin checks that the thing answering on the port really is one (/health carries a service marker). If some unrelated dev server holds 5199, you get a warning that says so and names the fix — rather than devtools that silently never connect with nothing in any log to explain it.

Security

The relay binds 127.0.0.1 by default: a relay nobody consciously started should not be reachable from the network. Pass host: "0.0.0.0" to let a phone on your LAN join the devtools window (your Vite server.host must expose the app too). If a LAN client asks a loopback-bound relay's dev server for status, it is told there is no relay — rather than handed a URL that can never connect — and the dev server logs the one-line fix.

The relay itself is unauthenticated and ephemeral — local dev only. It keeps no history and logs no content. See @nice-code/devtools-relay.

Not using Vite?

Discovery is a Vite-dev-server feature. A React Native client, a non-Vite dev server, or a relay running somewhere other than this machine should set relayUrl on the devtools config explicitly — an explicit URL always wins, and the client dials it directly without asking anyone.