feat: workbench dev server

[gu-stav]

Description

Important

This will go into a feature branch for now and won't be released to main anytime soon. It's main purpose is to unblock development of workbench and to showcase how we imagine the setup to work.

Setup a workbench dev-server running alongside the studio/ app dev-server. It uses temporary runtime files written to .sanity/workbench as Vite root, similar to how runtime for studios works today.

Instead of navigating to the running application directly, users will be prompted to open workbench instead, which is why the port in the config now refers to the workbench port. This is something that we will likely have to discuss further at some point, because it mixes application and workbench configuration.

This needs the following studio PR to work: sanity-io/sanity#12511, which exports renderWorkbench from @sanity/workbench.

Testing

This can be tested using the studio and CLI pre-release together, but it will still fail, because we don't have a remote target yet.

It nevertheless shows that the code that is being run comes from @sanity/workbench which is what we expect at this point:

[claude]

Claude finished @joshuaellis's task in 1m 54s —— View job

---

Code Review

• Gather context
• Read changed files
• Provide review feedback

---

packages/@sanity/cli/src/actions/dev/devAction.ts

Missing unit tests for orchestration logic. devAction.ts is now the top-level coordinator (port allocation + dual-server close), but there are no tests for it (coverage dropped to 64.3%). The critical paths not covered are:

• The if (!server) early-return when startAppDevServer exits without a server (missing orgId case)
• The workbench URL log message when closeWorkbenchServer !== undefined
• The Promise.allSettled close behavior

The tests for startWorkbenchDevServer and writeWorkbenchRuntime are solid, but devAction.ts itself has no test file. Fix this →

---

packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts line 58

strictPort: false on the workbench Vite config means Vite silently picks a different port if the requested one is occupied. The code correctly captures the actual port via server.httpServer?.address(). However, when this happens, the app server is assigned workbenchPort + 1 based on the requested port, not the actual port — because workbenchPort in devAction.ts comes from the resolved actualPort. Double-check: devAction.ts destructures workbenchPort from the return value of startWorkbenchDevServer, which returns workbenchPort: actualPort. So the app offset is computed from the actual port. This is correct — but the variable naming (workbenchPort shadowing the original requested port) could mislead future readers. Not a bug, but worth a comment.

---

packages/@sanity/cli/src/actions/dev/devAction.ts line 20

desiredAppPort is conditioned on closeWorkbenchServer === undefined rather than !workbenchAvailable. These are equivalent in practice (a failed server listen returns workbenchAvailable: false and no close), but using !workbenchAvailable would make the intent clearer: the port is reserved for workbench only when it's actually running.

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	35.7% (- 64.3%)
packages/@sanity/cli/src/actions/dev/hasFederationPackage.ts	100.0% (new)
packages/@sanity/cli/src/actions/dev/loadFederationVitePlugin.ts	100.0% (new)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	86.4% (±0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	95.0% (±0%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	100.0% (new)

Comparing 6 changed files against main @ 75d5154f6bd1eb3a9d344c1d65e91775c40ae345

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.0%)
Branches	72.7% (±0%)
Functions	83.2% (±0%)
Lines	83.4% (- 0.0%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	63.6% (- 36.4%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	86.4% (±0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	95.0% (±0%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	29.4% (new)

Comparing 4 changed files against main @ 75d5154f6bd1eb3a9d344c1d65e91775c40ae345

Overall Coverage

Metric	Coverage
Statements	82.9% (- 0.1%)
Branches	72.6% (- 0.0%)
Functions	83.2% (- 0.1%)
Lines	83.3% (- 0.1%)

[gu-stav]

@joshuaellis First iteration: what do you think about the approach?

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	63.6% (- 36.4%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	86.4% (±0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	95.0% (±0%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	29.4% (new)

Comparing 4 changed files against main @ 75d5154f6bd1eb3a9d344c1d65e91775c40ae345

Overall Coverage

Metric	Coverage
Statements	82.9% (- 0.1%)
Branches	72.6% (- 0.0%)
Functions	83.2% (- 0.1%)
Lines	83.3% (- 0.1%)

[gu-stav]

@joshuaellis Added a new branch SDK-1013 and pointed the PR to it ✅

[joshuaellis]

Good start on this, we probably need the federation package to be ready so we can change the runtime static file the dev/build commands create if federation is enabled & therefore render a shell for MF to pull in the workbench remotely?

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	70.6% (- 29.4%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	83.3% (- 3.0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	31.3% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 5 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	82.8% (- 0.2%)
Branches	72.6% (- 0.1%)
Functions	83.1% (- 0.1%)
Lines	83.3% (- 0.2%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	88.9% (- 11.1%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	83.3% (- 3.0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	100.0% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.0%)
Branches	72.6% (- 0.1%)
Functions	83.2% (- 0.0%)
Lines	83.4% (- 0.0%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	88.9% (- 11.1%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	83.3% (- 3.0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	100.0% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.0%)
Branches	72.6% (- 0.1%)
Functions	83.2% (- 0.0%)
Lines	83.4% (- 0.0%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	90.0% (- 10.0%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	83.3% (- 3.0%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	100.0% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.0%)
Branches	72.6% (- 0.1%)
Functions	83.2% (- 0.0%)
Lines	83.5% (- 0.0%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	84.2% (- 2.2%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.2% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.1%)
Branches	72.6% (- 0.1%)
Functions	83.1% (- 0.1%)
Lines	83.4% (- 0.1%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	84.2% (- 2.2%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.2% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	82.9% (- 0.1%)
Branches	72.5% (- 0.1%)
Functions	83.1% (- 0.1%)
Lines	83.4% (- 0.1%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	81.3% (- 5.1%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.2% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 133be82f2a246f5cc1573c8e2733d50a2b2ea746

Overall Coverage

Metric	Coverage
Statements	82.9% (- 0.1%)
Branches	72.5% (- 0.1%)
Functions	83.1% (- 0.1%)
Lines	83.4% (- 0.1%)

[github-actions]

Preview this PR with pkg.pr.new

Run the Sanity CLI

npx https://pkg.pr.new/sanity-io/cli/@sanity/cli@f5f0dac <command>

...Or upgrade project dependencies

📦 @sanity/cli

pnpm install https://pkg.pr.new/@sanity/cli@f5f0dac

📦 @sanity/cli-core

pnpm install https://pkg.pr.new/@sanity/cli-core@f5f0dac

📦 @sanity/cli-test

pnpm install https://pkg.pr.new/@sanity/cli-test@f5f0dac

📦 @sanity/eslint-config-cli

pnpm install https://pkg.pr.new/@sanity/eslint-config-cli@f5f0dac

View Commit (f5f0dac)

[joshuaellis]

since we're re-exporting @sanity/workbench from sanity do we need these checks anymore? do they do this for studio servers?

[gu-stav]

Imo we do need this check, because otherwise if dev is running with a version of sanity that does not export sanity/workbench the workbench dev-server would start, but couldn't render anything, because the export does not exist.

This ensures when the export does not exist, do not start the workbench dev-server and fallback to the current behavior (application dev-server is printed).

Does that make sense?

[joshuaellis]

But when do you think thats gonna happen? My understanding is we dont encourage anyone to actually install the cli manually, it comes from the sanity package incl. all the commands so i'm just wondering if we're guarding for a situation that won't happen?

[gu-stav]

For now this is a guard for ourselves, if we are running the CLI with e.g. a stable studio release. We could also do a hard fail in that case?

For the future: it depends - once we release this PR, workbench can only work, when the sanity package has the export. If users are running an old studio e.g. it will fail.

This may also happen if someone has a global old version of the CLI installed.

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	81.3% (- 5.1%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.2% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ a589b209fc16f8571129127883123e9862afda48

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.1%)
Branches	72.6% (- 0.1%)
Functions	83.2% (- 0.1%)
Lines	83.5% (- 0.1%)

[joshuaellis]

We don't want to have people install workbench directly. At the moment this follow a similar pattern to how people configure their cli as well where the studio re-exports the configuration function from the cli.

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	81.3% (- 5.1%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.2% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 272b2436eb408d53a93ffafb912401c63d62fcb0

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.1%)
Branches	72.6% (- 0.1%)
Functions	83.2% (- 0.1%)
Lines	83.5% (- 0.1%)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	81.3% (- 5.1%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.7% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 272b2436eb408d53a93ffafb912401c63d62fcb0

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.1%)
Branches	72.6% (- 0.1%)
Functions	83.2% (- 0.1%)
Lines	83.5% (- 0.1%)

[github-actions]

📦 Bundle Stats — @sanity/cli

Compared against feat/workbench (b7b69c82) · v6.3.1 (npm)

@sanity/cli

Metric	Value	vs feat/workbench (b7b69c8)	vs v6.3.1
Internal (raw)	2.1 KB	-	-
Internal (gzip)	799 B	-	-
Bundled (raw)	11.06 MB	-	+9.12 MB, +470.6%
Bundled (gzip)	2.07 MB	-	+1.60 MB, +335.7%
Import time	918ms	+2ms, +0.2%	+16ms, +1.7%

bin:sanity

Metric	Value	vs feat/workbench (b7b69c8)	vs v6.3.1
Internal (raw)	975 B	-	-
Internal (gzip)	460 B	-	-
Bundled (raw)	9.83 MB	-	+9.12 MB, +1286.7%
Bundled (gzip)	1.77 MB	-	+1.60 MB, +940.0%
Import time	NaNs	-	NaNs, NaN%

🗺️ View treemap · Artifacts

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

📦 Bundle Stats — @sanity/cli-core

Compared against feat/workbench (b7b69c82) · v1.3.0 (npm)

Metric	Value	vs feat/workbench (b7b69c8)	vs v1.3.0
Internal (raw)	92.2 KB	-	-
Internal (gzip)	21.6 KB	-	-
Bundled (raw)	21.64 MB	-	+9.12 MB, +72.9%
Bundled (gzip)	3.43 MB	-	+1.59 MB, +86.9%
Import time	855ms	-11ms, -1.3%	+45ms, +5.6%

🗺️ View treemap · Artifacts

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	82.3% (- 4.6%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.7% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 6c351ae1c4a5c433fce73b287d18c40f2a22a3bc

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.1%)
Branches	72.8% (- 0.1%)
Functions	83.2% (- 0.1%)
Lines	83.5% (- 0.0%)

[binoy14]

just one change looks good otherwise

[binoy14]

use resolveLocalPackage util instead

[joshuaellis]

changed.

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/src/actions/dev/devAction.ts	64.3% (- 35.7%)
packages/@sanity/cli/src/actions/dev/startAppDevServer.ts	82.3% (- 4.6%)
packages/@sanity/cli/src/actions/dev/startStudioDevServer.ts	93.3% (- 1.7%)
packages/@sanity/cli/src/actions/dev/startWorkbenchDevServer.ts	95.7% (new)
packages/@sanity/cli/src/actions/dev/writeWorkbenchRuntime.ts	100.0% (new)
packages/@sanity/cli/src/commands/dev.ts	100.0% (±0%)

Comparing 6 changed files against main @ 7b98e0be69544a0a89ddf871219b8025128e622b

Overall Coverage

Metric	Coverage
Statements	83.0% (- 0.1%)
Branches	72.8% (- 0.1%)
Functions	83.2% (- 0.1%)
Lines	83.5% (- 0.0%)