Command.Dev reference

Dev

Source: src/Command/Dev.ts

A long-lived shell process scoped to a stack instance, started during alchemy dev and restarted when its inputs change. During alchemy deploy this is a no-op — Dev resources only run in dev mode.

The child process runs inside the dev sidecar (see Command/Local.ts) so it survives user-code HMR — Alchemy’s user process can restart without killing your npm run dev server. Its stdout/stderr are mirrored to the terminal (preserving colored output) and scanned for an http(s)://… URL, favoring a localhost/IP URL (the dev server’s own address) over any unrelated URL the command prints first. The result is exposed as the url output attribute — useful for surfacing a dev server’s local URL back out to whatever resource declared this Dev.

Dev: Basic Usage

Pass a shell command that starts a long-lived dev server. Alchemy runs it in the background and extracts the first URL it prints.

const dev = yield* Dev("Frontend", {
  command: "npm run dev",
});
yield* Console.log(dev.url); // e.g. "http://localhost:5173"

Dev: Requiring a URL

By default the resource waits 5 seconds for a URL and settles with url: undefined if none appears. Set waitForUrl when downstream resources depend on the URL: the resource is ready only once the command prints one, however long the server takes to start, and fails if the command exits first.

const engine = yield* Dev("Engine", {
  command: "rivet-engine start",
  waitForUrl: true,
});

Dev: Known Port

When you choose the port, pass it as port: Alchemy sets PORT to it and the resource is ready once the port accepts a connection, with no output scanning. This suits servers that print no URL, and wrappers that route the port elsewhere.

const api = yield* Dev("Api", {
  command: "node server.ts",
  port: 4000,
});
yield* Console.log(api.url); // "http://localhost:4000"

Dev: Working Directory

Use cwd to run the command in a subdirectory — useful in monorepos where each package has its own dev server.

const dev = yield* Dev("Web", {
  command: "npm run dev",
  cwd: "apps/web",
});

Dev: Environment Variables

Extra environment variables are merged on top of process.env. Sensitive values can be wrapped in Redacted to keep them out of logs and state files.

const dev = yield* Dev("Api", {
  command: "npm run dev",
  env: {
    PORT: "4000",
    DATABASE_URL: Redacted.make("postgres://..."),
  },
});