@devries-cameron20 / t3code Mirror · read-only / commits / 1dfb572871
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 20:45 UTC

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);