Local Development

Spin up a full local Sui environment — network, accounts, published packages, a dev wallet, and your frontend — with a single devstack up. This is the default mode; the example below is the shape of a typical local stack. Include sui() once in any stack whose members depend on Sui.

import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

import {
	defineDevstack,
	account,
	HOST_SERVICE_PORT_TOKEN,
	hostService,
	localPackage,
	sui,
	wallet,
} from '@mysten-incubation/devstack';

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

const localnet = sui();
const alice = account('alice');
const hello = localPackage('hello', {
	sourcePath: resolve(HERE, 'move/hello'),
	publisher: alice,
});
const devWallet = wallet({
	accounts: [alice],
});
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: [hello, devWallet] as const,
});

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

Stack state

State is scoped by app and stack name:

.devstack/
  stacks/
    main/
      manifest.json
      deployment.json
      roster.json
      stack.lock
      cache/
      snapshots/

A hostService(...) dev server is reached through a stable routed endpoint — http://dev.<app>.localhost:5175 for the default stack — even though its raw process port may change between runs. Non-default stacks insert the stack segment: http://dev.<stack>.<app>.localhost:5175. See Dev servers for ports and routing, and Refs and dependencies for how plugins publish named endpoints.

Outputs

Two kinds of output live in different places:

• The committed src/generated tree, written by devstack codegen. It is id-free and shared across every stack.
• The per-stack deployment.json, written under .devstack/stacks/<stack>/ by devstack up / devstack apply. It carries the live ids, accounts, and dev-wallet connection for one stack.

See Codegen for the full model.

Commands

devstack up --renderer tui
devstack up --renderer plain
devstack apply
devstack status --json

devstack apply is safe to run while devstack up owns the same stack: it reconciles against the live session and re-emits the per-stack deployment file and dev extras. If the stack is not live, it reconciles in a one-shot run. The generated src/generated tree stays the domain of devstack codegen.

Use a different stack name when you want independent keys, snapshots, runtime state, and deployment file — the generated src/generated tree stays shared across all of them:

DEVSTACK_STACK=ci devstack apply
devstack apply --stack ci