Dev Servers

Use hostService(...) for a browser dev server or any other host process that should start and stop with devstack up.

import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import {
	HOST_SERVICE_PORT_TOKEN,
	defineDevstack,
	hostService,
	sui,
	wallet,
} from '@mysten-incubation/devstack';

const HERE = dirname(fileURLToPath(import.meta.url));
const DEV_PORT = 5173;

const localnet = sui();
const devWallet = wallet({
	accounts: 'all',
});

const app = hostService({
	name: 'app',
	script: `pnpm exec vite --host 127.0.0.1 --strictPort --port ${HOST_SERVICE_PORT_TOKEN}`,
	cwd: HERE,
	port: DEV_PORT,
	ready: { kind: 'http' },
	after: [devWallet] as const,
});

export default defineDevstack({ members: [localnet, app], stackName: 'main' });

Port Assignment And Routing

There are two ports involved:

• The host process port is the port Vite actually binds. Set port as a preferred value, or omit it and devstack will allocate a free port automatically. HOST_SERVICE_PORT_TOKEN is replaced with the allocated process port before the command starts.
• The routed dev endpoint is the stable browser-facing URL. For the default dev server endpoint, the router serves http://dev.<app>.localhost:5175 and forwards traffic to whatever process port was allocated.

That means the raw process port can change between runs while the routed URL stays predictable. Open the routed URL when you want stack-scoped browser behavior, wallet origin checks, Playwright base URLs, and links from the manifest to converge. Use the direct 127.0.0.1:<process-port> URL only for low-level debugging.

Use script for normal dev commands, and use command plus args only when you need argv-level control.

hostService(...) returns a plugin resource ref. Set after to order the process after packages, wallet, or service members it needs, and set ready to the readiness probe the supervisor should wait for before treating the service as started.