[wmadden-electric]

Linked issue

n/a. Part of the local-dev work; the plan is in .drive/projects/emulator-commands/.

Summary

prisma dev --detach brings the app up, waits until every service answers, prints the URLs, and returns:

$ prisma dev module.ts --detach
dev: ready
gateway: http://localhost:3001
quotes: http://localhost:3000
$ curl http://localhost:3001       # same terminal; the app keeps running
$ prisma dev stop                  # stops it

Decision: prisma dev stays in the foreground by default. It watches your build output, redeploys on change, and stops the app on Ctrl-C, exactly as before. Running the app in the background is opt-in with --detach. ADR-0053 records this.

Why

Agents and scripts don't want a long-running foreground process. Today they have to background prisma dev themselves and watch its output for "ready". With --detach, the exit code answers the question:

• 0: every service answers.
• Non-zero: the start failed, and the same error is printed as in the foreground.

The app then runs until prisma dev stop.

What --detach does

A detached run goes through the same steps as prisma dev up to "ready". It deploys the app to the local emulators, Composer's local stand-ins for Prisma Cloud. It then waits until every service accepts connections, because the emulator reports a service as running only once its port answers. Then it returns.

It starts no file watcher and doesn't stop the app on exit. The dev operation in @prisma/composer/control takes the same detach option. The session it returns is already closed, and its stop() does nothing.

When something goes wrong

• A detached run that fails before ready stops the app. That includes an app an earlier --detach left running, because a failed redeploy has already replaced that service's old process. The docs say so, and tell you to fix the build and run --detach again.
• Ctrl-C before ready stops the app and exits 130.
• --detach combines with --fresh and --name.

Testing performed

• Unit tests:
  • A detached run never starts the file watcher and never stops a service.
  • The command exits 0 with the URLs.
  • Ctrl-C before ready stops the app.
• test/integration/test/local-dev-detach.integration.ts, which runs the installed prisma binary against real emulators in a temporary directory:
  • --detach exits 0, and both services still answer afterwards.
  • Stopping the app closes every service and database port.
  • A detached run that fails during deployment leaves no port open.
  • Its services use ports from 3200 up, so other local servers can't affect the result.
• The CLI tests, pnpm build, typecheck, the lints, the docs checks, and the local-dev integration scripts, each run on its own.

Checklist

• All commits are signed off (git commit -s) per the DCO. The DCO status check will block merge if any commit is missing a Signed-off-by: trailer.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• The PR title is a conventional commit (feat, fix, chore, docs, refactor, test, build) — PR titles drive the auto-generated release notes.
• Tests are updated (or n/a if the change is doc-only / refactor with no behavioural delta).

Notes for the reviewer

• Stacked on feat(dev): prisma dev url prints where a local service answers; add prisma dev stop and prisma emulator list #357 (prisma dev url, prisma dev stop, prisma emulator list). It retargets to main as the stack merges.
• The integration script calls devStop directly. The installed prisma binary doesn't mount prisma dev stop yet, so the script calls the devStop operation, which is the code that command runs.
• The guide's scripting example uses prisma dev url gateway --format human, because a piped prisma command still prints JSON until feat!: piping a prisma command gives its plain data; JSON needs --json prisma-cli#353 lands.
• Docs updated: ADR-0053, an amendment note on ADR-0041, the ADR index, local-dev.md, the running-locally guide and the core-concepts skill.
• Deferred: a run-then-stop mode such as prisma dev --exec "npm test", like Firebase's emulators:exec. It's recorded in deferred.md.

Alternatives considered

• Background by default, with --watch for the foreground loop. Simpler for agents, but against prior art: Docker Compose (up -d --wait), .NET Aspire (run --detach), Laravel Sail (up -d) and Prisma ORM's own prisma dev --detach all default to the foreground. The ORM's prisma dev ships in the same prisma binary, so the two would contradict each other.
• A separate prisma dev start. It reads naturally next to dev stop, but it adds a second spelling of the run command. --detach is the name the ORM's prisma dev and Docker already use.

Agent: attila-51

🤖 Generated with Claude Code

[prisma-gizmo]

✅ Gizmo reviewed d456f13 — posted 0 inline comment(s) this pass.

Open findings: none

Change walkthrough

This incremental delta layers release 0.30.0 bookkeeping, an emulator-behavior doc amendment, and integration-test hardening on top of the already-reviewed prisma dev --detach feature.

Emulator docs (docs/design/10-domains/local-dev.md). The readiness and concurrency sections now describe what compute-main.ts implements: listens: false is recorded in the artifact's compute.manifest.json and honored per deployment; readiness probes loopback on both 127.0.0.1 and ::1 every 50 ms (--ready-poll-ms exists but the CLI never passes it); and a start whose process has already exited is no longer joined by a concurrent resume or redeploy — the newcomer starts the service again, matching joinableStart's processExited check.

Skill and version bumps (skills/prisma-composer-core-concepts/SKILL.md, test/integration/package.json, website). The 0.29.1 → 0.30.0 bump is consistent across the public packages, integration tests, and website, and the alchemy pin moves to 2.0.0-beta.83, matching composer's dependency and the lockfile. The skill's new paragraph on node-address identity (logicalId on Branch, rename/id/module changes creating new entities and deleting database or bucket data) restates the same rule added to the deploying guide, so the two docs agree.

Integration tests. local-dev-detach.integration.ts and the sibling control.dev-current.test.ts now throw a descriptive error when creating a placeholder instance in the emulator's admin API returns a non-2xx status. Previously such a response would surface later as a confusing missing-port parse failure; the guard keeps the success path reading the body exactly once and applies the same pattern in both tests.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 100811e9-5ed1-4bb4-a81b-5c876a8f3b43

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@363

npm i https://pkg.pr.new/@prisma/composer-cli@363

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@363

commit: 9112f57

[prisma-gizmo]

New findings: 🟡 1 minor · trace

[prisma-gizmo]

New findings: 🟡 1 minor · trace

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.