The best way to control Claude Code, Codex and more from any computer or phone
perf(dev): faster first load for shared dev servers (#22776)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 21, 2026 at 02:34 UTC
1dfb57287174230e5c386e452f54bb0cce2fc32f
8 files changed
+188
-32
apps/server/package.json
+1
@@ -16,6 +16,7 @@
16
"type": "module",
17
"scripts": {
18
"dev": "node --watch --watch-path=src --watch-path=../../packages --watch-path=package.json src/bin.ts",
19
+ "dev:built": "vp run dev",
20
"build:bundle": "vp pack",
21
"build:exe": "node scripts/cli.ts build-exe",
22
"start": "node dist/bin.mjs",
apps/server/src/http.ts
+8
@@ -581,6 +581,14 @@ const handleStaticAndDevRequest = Effect.fn("handleStaticAndDevRequest")(
581
582
const staticDir =
583
config.staticDir ?? (config.devUrl ? yield* ServerConfig.resolveStaticDir() : undefined);
584
+ if (!staticDir && config.devUrl) {
585
+ // `vp run dev --share --built` prints the pairing URL before its first
586
+ // web build lands in apps/web/dist. Reload until it does.
587
+ return HttpServerResponse.text(
588
+ '<!doctype html><meta http-equiv="refresh" content="2"><p>Waiting for the first web build. This page reloads by itself.</p>',
589
+ { status: 503, contentType: "text/html", headers: { "Retry-After": "2" } },
590
+ );
591
+ }
592
if (!staticDir) {
593
return HttpServerResponse.text("No static directory configured and no dev URL set.", {
594
status: 503,
apps/web/package.json
+1
@@ -6,6 +6,7 @@
6
"scripts": {
7
"build:ghostty-wasm": "bash scripts/build-libghostty-wasm.sh",
8
"dev": "vp dev",
9
+ "dev:built": "vp build --watch",
10
"build": "vp build",
11
"preview": "vp preview",
12
"test": "vp test run --passWithNoTests --project unit --project browser"
apps/web/vite.config.ts
+15
-9
@@ -62,6 +62,10 @@ const configuredHostedAppUrl = (() => {
62
})();
63
const sourcemapEnv = process.env.T3CODE_WEB_SOURCEMAP?.trim().toLowerCase();
64
65
+// `vp run dev --share --built` rebuilds on every change. The license manifest
66
+// is about 2 s of each build, and nothing in that mode reads it.
67
+const builtDev = process.env.T3CODE_BUILT_DEV === "1";
68
+
69
const bundledDevEnv = process.env.T3CODE_BUNDLED_DEV?.trim().toLowerCase();
70
const bundledDev = bundledDevEnv === "1" || bundledDevEnv === "true";
71
@@ -196,15 +200,17 @@ export default defineConfig(() => {
200
assetsInclude: ["**/*.wasm"],
201
plugins: [
202
devCompressionPlugin(),
199
- thirdPartyLicensesPlugin({
200
- bundleName: "web",
201
- configFile: new URL("../../third-party-licenses.config.json", import.meta.url),
202
- packageManifests: [
203
- { bundle: "web", path: new URL("./package.json", import.meta.url) },
204
- { bundle: "server", path: new URL("../server/package.json", import.meta.url) },
205
- { bundle: "desktop", path: new URL("../desktop/package.json", import.meta.url) },
206
- ],
207
- }),
203
+ builtDev
204
+ ? undefined
205
+ : thirdPartyLicensesPlugin({
206
+ bundleName: "web",
207
+ configFile: new URL("../../third-party-licenses.config.json", import.meta.url),
208
+ packageManifests: [
209
+ { bundle: "web", path: new URL("./package.json", import.meta.url) },
210
+ { bundle: "server", path: new URL("../server/package.json", import.meta.url) },
211
+ { bundle: "desktop", path: new URL("../desktop/package.json", import.meta.url) },
212
+ ],
213
+ }),
214
tanstackRouter({ autoCodeSplitting: true }),
215
react({ compiler: true }),
216
tailwindPlugins(bundledDev),
docs/operations/development.md
+8
@@ -60,6 +60,14 @@ The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts),
60
[Tailwind plugin](../../apps/web/vite/tailwind.ts), and
61
[startup warmup](../../apps/web/vite/warmBundledDev.ts).
62
63
+`vp run dev --share --built` skips the Vite dev server. It runs `vp build --watch` for the web
64
+app, and the backend serves `apps/web/dist` on the same tailnet URL and pairing flow. Use it when
65
+someone tests over a slow link or only needs to use the app: loads are production size, and the
66
+first load does not wait for dev bundling. There is no HMR. After an edit, wait for the
67
+`built in` line (about 6 s), then reload. Until the first build exists, the URL shows a page that
68
+reloads by itself. The license manifest is not generated in this mode. `--built` requires
69
+`--share` and the `dev` mode.
70
+
71
#### Reusable dev credential
72
73
Use this only on a hostname where you trust every service. Browsers send cookies to all ports
scripts/dev-runner.test.ts
+76
-4
@@ -62,6 +62,7 @@ const devServerInput = {
62
devUrl: undefined,
63
dryRun: false,
64
share: false,
65
+ built: false,
66
runArgs: ["--inspect", "secret-token-value"],
67
} as const;
68
@@ -420,10 +421,16 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
421
// per-module waterfall pays a tailnet round trip per import level. The
422
// runner defaults bundled dev on for the spawned stack, but only
423
// defaults: an explicit T3CODE_BUNDLED_DEV (even "0") must pass through.
423
- describe("--share bundled dev default", () => {
424
- const shareSpawnedEnv = (input: { readonly ambientBundledDev: string | undefined }) =>
424
+ describe("--share spawn wiring", () => {
425
+ const shareSpawned = (input: {
426
+ readonly ambientBundledDev?: string | undefined;
427
+ readonly built?: boolean;
428
+ readonly host?: string;
429
+ }) =>
430
Effect.gen(function* () {
431
let captured: Record<string, string | undefined> | undefined;
432
+ let vpArgs: ReadonlyArray<string> = [];
433
+ const tailscaleCalls: Array<ReadonlyArray<string>> = [];
434
const spawnerLayer = Layer.succeed(
435
ChildProcessSpawner.ChildProcessSpawner,
436
ChildProcessSpawner.make((command) => {
@@ -434,8 +441,10 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
441
};
442
if (spawned.command === "vp") {
443
captured = spawned.options?.env;
444
+ vpArgs = spawned.args;
445
return Effect.succeed(mockProcess(0));
446
}
447
+ tailscaleCalls.push(spawned.args);
448
return Effect.succeed(
449
ChildProcessSpawner.makeHandle({
450
pid: ChildProcessSpawner.ProcessId(2),
@@ -465,6 +474,8 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
474
mode: "dev",
475
port: undefined,
476
share: true,
477
+ built: input.built ?? false,
478
+ host: input.host,
479
}).pipe(
480
Effect.provide(Layer.mergeAll(emptyConfigLayer, netServiceLayer, spawnerLayer)),
481
Effect.provideService(HostProcess.Platform, "linux"),
@@ -476,15 +487,76 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
487
),
488
);
489
479
- return captured;
490
+ return { env: captured, vpArgs, tailscaleCalls };
491
});
492
493
it.effect("keeps an explicit T3CODE_BUNDLED_DEV=0 opt-out", () =>
494
Effect.gen(function* () {
484
- const env = yield* shareSpawnedEnv({ ambientBundledDev: "0" });
495
+ const { env } = yield* shareSpawned({ ambientBundledDev: "0" });
496
assert.equal(env?.T3CODE_BUNDLED_DEV, "0");
497
}),
498
);
499
+
500
+ it.effect("--built serves the backend on the web port's tailnet URL", () =>
501
+ Effect.gen(function* () {
502
+ const { env, vpArgs, tailscaleCalls } = yield* shareSpawned({ built: true });
503
+ assert.include(vpArgs, "dev:built");
504
+ assert.equal(env?.T3CODE_BUILT_DEV, "1");
505
+ assert.equal(env?.T3CODE_BUNDLED_DEV, undefined);
506
+ assert.equal(env?.VITE_DEV_SERVER_URL, `https://host.example.ts.net:${env?.PORT}/`);
507
+ const serve = tailscaleCalls.find((args) => args.includes("--bg"));
508
+ assert.deepEqual(serve?.slice(-2), [
509
+ `--https=${env?.PORT}`,
510
+ `http://127.0.0.1:${env?.T3CODE_PORT}`,
511
+ ]);
512
+ }),
513
+ );
514
+
515
+ it.effect("--built --host ::1 targets the backend's IPv6 loopback", () =>
516
+ Effect.gen(function* () {
517
+ const { env, tailscaleCalls } = yield* shareSpawned({ built: true, host: "::1" });
518
+ const serve = tailscaleCalls.find((args) => args.includes("--bg"));
519
+ assert.equal(serve?.at(-1), `http://[::1]:${env?.T3CODE_PORT}`);
520
+ }),
521
+ );
522
+
523
+ it.effect("without --built keeps Vite behind the tailnet URL", () =>
524
+ Effect.gen(function* () {
525
+ const { env, vpArgs, tailscaleCalls } = yield* shareSpawned({});
526
+ assert.include(vpArgs, "dev");
527
+ assert.notInclude(vpArgs, "dev:built");
528
+ assert.equal(env?.T3CODE_BUNDLED_DEV, "1");
529
+ const serve = tailscaleCalls.find((args) => args.includes("--bg"));
530
+ assert.equal(serve?.at(-1), `http://localhost:${env?.PORT}`);
531
+ }),
532
+ );
533
+ });
534
+
535
+ it.effect.each([
536
+ { mode: "dev", share: false },
537
+ { mode: "dev:web", share: true },
538
+ { mode: "dev:desktop", share: true },
539
+ ] as const)("rejects --built for $mode with share=$share", ({ mode, share }) => {
540
+ const spawnerLayer = Layer.succeed(
541
+ ChildProcessSpawner.ChildProcessSpawner,
542
+ ChildProcessSpawner.make(() => Effect.succeed(mockProcess(0))),
543
+ );
544
+
545
+ return Effect.gen(function* () {
546
+ const error = yield* runDevRunnerWithInput({
547
+ ...devServerInput,
548
+ mode,
549
+ port: undefined,
550
+ share,
551
+ built: true,
552
+ }).pipe(
553
+ Effect.provide(Layer.mergeAll(emptyConfigLayer, netServiceLayer, spawnerLayer)),
554
+ Effect.provideService(HostProcess.Platform, "linux"),
555
+ Effect.flip,
556
+ );
557
+
558
+ assert.equal(error._tag, "DevRunnerBuiltNeedsShareError");
559
+ });
560
});
561
562
it.effect("reports non-zero exits without manufacturing a cause", () => {
scripts/dev-runner.ts
+71
-17
@@ -84,6 +84,16 @@ const MODE_ARGS = {
84
"dev:desktop": ["run", "--filter=@t3tools/desktop", "--filter=@t3tools/web", "dev"],
85
} as const satisfies Record<string, ReadonlyArray<string>>;
86
87
+// `--built`: the web package rebuilds into apps/web/dist and the backend serves
88
+// it, so no Vite dev server runs.
89
+const BUILT_DEV_ARGS = [
90
+ "run",
91
+ "--filter=@t3tools/web",
92
+ "--filter=t3",
93
+ "--parallel",
94
+ "dev:built",
95
+] as const;
96
+
97
type DevMode = keyof typeof MODE_ARGS;
98
/**
99
* `role` matters because only the backend honours `--host`/`T3CODE_HOST`; the
@@ -184,6 +194,17 @@ export class DevRunnerHostNotProxiableError extends Schema.TaggedError<DevRunner
194
}
195
}
196
197
+export class DevRunnerBuiltNeedsShareError extends Schema.TaggedError<DevRunnerBuiltNeedsShareError>()(
198
+ "DevRunnerBuiltNeedsShareError",
199
+ {
200
+ mode: Schema.Literals(["dev", "dev:server", "dev:web", "dev:desktop"]),
201
+ },
202
+) {
203
+ override get message(): string {
204
+ return `--built only works with \`dev --share\` (got ${this.mode}${this.mode === "dev" ? " without --share" : ""}): the backend serves the built client on the tailnet URL.`;
205
+ }
206
+}
207
+
208
const optionalStringConfig = (name: string): Config.Config<string | undefined> =>
209
Config.String(name).pipe(
210
Config.option,
@@ -659,6 +680,7 @@ interface DevRunnerCliInput {
680
readonly dryRun: boolean;
681
readonly share: boolean;
682
readonly seed?: boolean | undefined;
683
+ readonly built: boolean;
684
readonly runArgs: ReadonlyArray<string>;
685
}
686
@@ -683,6 +705,10 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
705
return yield* new DevRunnerHostNotProxiableError({ mode: input.mode, host: input.host });
706
}
707
708
+ if (input.built && (input.mode !== "dev" || !input.share)) {
709
+ return yield* new DevRunnerBuiltNeedsShareError({ mode: input.mode });
710
+ }
711
+
712
const worktreePath = yield* resolveGitWorktreePath(yield* HostProcess.WorkingDirectory);
713
714
const { offset, source } = yield* resolveOffset({
@@ -743,6 +769,7 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
769
}
770
771
const sharedWebPort = BASE_WEB_PORT + webOffset;
772
+ let built = false;
773
if (input.share) {
774
if (input.mode === "dev:server") {
775
yield* Effect.logInfo("[dev-runner] --share has no effect for dev:server (no web server).");
@@ -755,18 +782,32 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
782
// process (and reboots), so the cleanup has to be registered atomically
783
// with creating it. An interrupt landing in between would otherwise
784
// leave a mapping pointing at a port nothing is listening on.
758
- const shared = yield* Effect.acquireRelease(shareDevServer({ webPort: sharedWebPort }), () =>
759
- unshareDevServer(sharedWebPort).pipe(
760
- Effect.flatMap((result) =>
761
- result.cleared
762
- ? Effect.void
763
- : Effect.logWarning(
764
- `[dev-runner] could not remove the tailnet mapping for port ${String(sharedWebPort)}${
765
- result.explanation ? `: ${result.explanation}` : ""
766
- }. Remove it with \`tailscale serve --https=${String(sharedWebPort)} off\`.`,
767
- ),
785
+ const shared = yield* Effect.acquireRelease(
786
+ shareDevServer({
787
+ webPort: sharedWebPort,
788
+ // The backend binds 127.0.0.1 unless --host changes it. A wildcard
789
+ // still answers there; `--host ::1` binds only the IPv6 loopback.
790
+ ...(input.built
791
+ ? {
792
+ localTarget: {
793
+ port: Number(env.T3CODE_PORT),
794
+ host: ["::1", "[::1]"].includes(input.host?.trim() ?? "") ? "[::1]" : "127.0.0.1",
795
+ },
796
+ }
797
+ : {}),
798
+ }),
799
+ () =>
800
+ unshareDevServer(sharedWebPort).pipe(
801
+ Effect.flatMap((result) =>
802
+ result.cleared
803
+ ? Effect.void
804
+ : Effect.logWarning(
805
+ `[dev-runner] could not remove the tailnet mapping for port ${String(sharedWebPort)}${
806
+ result.explanation ? `: ${result.explanation}` : ""
807
+ }. Remove it with \`tailscale serve --https=${String(sharedWebPort)} off\`.`,
808
+ ),
809
+ ),
810
),
769
- ),
811
).pipe(
812
Effect.tapError((error: DevShareError) =>
813
Effect.logWarning(
@@ -792,14 +833,21 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
833
if (input.devUrl === undefined) {
834
env.VITE_DEV_SERVER_URL = shared.url;
835
}
795
- // A shared origin serves a remote browser, where unbundled dev's
796
- // per-module requests each pay a tailnet round trip — a cold module
797
- // graph takes minutes to first paint. Bundled dev collapses that to a
798
- // few chunk requests.
799
- if (env.T3CODE_BUNDLED_DEV === undefined) {
836
+ if (input.built) {
837
+ built = true;
838
+ env.T3CODE_BUILT_DEV = "1";
839
+ } else if (env.T3CODE_BUNDLED_DEV === undefined) {
840
+ // A shared origin serves a remote browser, where unbundled dev's
841
+ // per-module requests each pay a tailnet round trip — a cold module
842
+ // graph takes minutes to first paint. Bundled dev collapses that to a
843
+ // few chunk requests.
844
env.T3CODE_BUNDLED_DEV = "1";
845
}
846
yield* Effect.logInfo(`[dev-runner] shared on tailnet: ${shared.url}`);
847
+ } else if (input.built) {
848
+ yield* Effect.logWarning(
849
+ "[dev-runner] --built needs the tailnet share; running the Vite dev server instead.",
850
+ );
851
}
852
}
853
}
@@ -812,7 +860,7 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
860
env,
861
});
862
815
- const args = [...MODE_ARGS[input.mode], ...input.runArgs];
863
+ const args = [...(built ? BUILT_DEV_ARGS : MODE_ARGS[input.mode]), ...input.runArgs];
864
const spawnCommand = yield* resolveSpawnCommand("vp", args, { env });
865
const processContext = {
866
mode: input.mode,
@@ -920,6 +968,12 @@ const devRunnerCli = Command.make("dev-runner", {
968
),
969
Flag.withFallbackConfig(optionalBooleanConfig("T3CODE_DEV_SEED")),
970
),
971
+ built: Flag.Boolean("built").pipe(
972
+ Flag.withDescription(
973
+ "With --share: serve a production web build from the backend instead of the Vite dev server. Rebuilds on change, no HMR, much smaller remote loads.",
974
+ ),
975
+ Flag.withDefault(false),
976
+ ),
977
runArgs: Argument.String("run-arg").pipe(
978
Argument.withDescription("Additional Vite+ run args (pass after `--`)."),
979
Argument.variadic(),
scripts/lib/dev-share.ts
+8
-2
@@ -127,8 +127,14 @@ export interface DevShareResult {
127
readonly host: string;
128
}
129
130
+/**
131
+ * Publishes `webPort` on the tailnet. The tailnet port always matches the web
132
+ * port so the URL is stable; `localTarget` points it at the backend instead
133
+ * when the backend serves a built client (`--built`).
134
+ */
135
export const shareDevServer = Effect.fn("devShare.shareDevServer")(function* (input: {
136
readonly webPort: number;
137
+ readonly localTarget?: { readonly port: number; readonly host: string };
138
}) {
139
const status = yield* readTailscaleStatus.pipe(
140
Effect.mapError((error) => new TailscaleUnavailableError({ cause: error })),
@@ -155,9 +161,9 @@ export const shareDevServer = Effect.fn("devShare.shareDevServer")(function* (in
161
// first, so it only binds the IPv6 loopback and a 127.0.0.1 target has
162
// nothing behind it (tailscale answers 502).
163
yield* ensureTailscaleServe({
158
- localPort: input.webPort,
164
+ localPort: input.localTarget?.port ?? input.webPort,
165
servePort: input.webPort,
160
- localHost: "localhost",
166
+ localHost: input.localTarget?.host ?? "localhost",
167
}).pipe(
168
Effect.mapError((error) => {
169
const explanation = explainCommandFailure(error);