Skip to content

Commit 1dfb572

Browse files
t3dotggclaude
andauthored
perf(dev): faster first load for shared dev servers (#22776)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 1f4eae7 commit 1dfb572

8 files changed

Lines changed: 188 additions & 32 deletions

File tree

‎apps/server/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
"type": "module",
1717
"scripts": {
1818
"dev": "node --watch --watch-path=src --watch-path=../../packages --watch-path=package.json src/bin.ts",
19+
"dev:built": "vp run dev",
1920
"build:bundle": "vp pack",
2021
"build:exe": "node scripts/cli.ts build-exe",
2122
"start": "node dist/bin.mjs",

‎apps/server/src/http.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -581,6 +581,14 @@ const handleStaticAndDevRequest = Effect.fn("handleStaticAndDevRequest")(
581581

582582
const staticDir =
583583
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+
}
584592
if (!staticDir) {
585593
return HttpServerResponse.text("No static directory configured and no dev URL set.", {
586594
status: 503,

‎apps/web/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"scripts": {
77
"build:ghostty-wasm": "bash scripts/build-libghostty-wasm.sh",
88
"dev": "vp dev",
9+
"dev:built": "vp build --watch",
910
"build": "vp build",
1011
"preview": "vp preview",
1112
"test": "vp test run --passWithNoTests --project unit --project browser"

‎apps/web/vite.config.ts‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,10 @@ const configuredHostedAppUrl = (() => {
6262
})();
6363
const sourcemapEnv = process.env.T3CODE_WEB_SOURCEMAP?.trim().toLowerCase();
6464

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+
6569
const bundledDevEnv = process.env.T3CODE_BUNDLED_DEV?.trim().toLowerCase();
6670
const bundledDev = bundledDevEnv === "1" || bundledDevEnv === "true";
6771

@@ -196,15 +200,17 @@ export default defineConfig(() => {
196200
assetsInclude: ["**/*.wasm"],
197201
plugins: [
198202
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+
}),
208214
tanstackRouter({ autoCodeSplitting: true }),
209215
react({ compiler: true }),
210216
tailwindPlugins(bundledDev),

‎docs/operations/development.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,14 @@ The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts),
6060
[Tailwind plugin](../../apps/web/vite/tailwind.ts), and
6161
[startup warmup](../../apps/web/vite/warmBundledDev.ts).
6262

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+
6371
#### Reusable dev credential
6472

6573
Use this only on a hostname where you trust every service. Browsers send cookies to all ports

‎scripts/dev-runner.test.ts‎

Lines changed: 76 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ const devServerInput = {
6262
devUrl: undefined,
6363
dryRun: false,
6464
share: false,
65+
built: false,
6566
runArgs: ["--inspect", "secret-token-value"],
6667
} as const;
6768

@@ -420,10 +421,16 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
420421
// per-module waterfall pays a tailnet round trip per import level. The
421422
// runner defaults bundled dev on for the spawned stack, but only
422423
// 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+
}) =>
425430
Effect.gen(function* () {
426431
let captured: Record<string, string | undefined> | undefined;
432+
let vpArgs: ReadonlyArray<string> = [];
433+
const tailscaleCalls: Array<ReadonlyArray<string>> = [];
427434
const spawnerLayer = Layer.succeed(
428435
ChildProcessSpawner.ChildProcessSpawner,
429436
ChildProcessSpawner.make((command) => {
@@ -434,8 +441,10 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
434441
};
435442
if (spawned.command === "vp") {
436443
captured = spawned.options?.env;
444+
vpArgs = spawned.args;
437445
return Effect.succeed(mockProcess(0));
438446
}
447+
tailscaleCalls.push(spawned.args);
439448
return Effect.succeed(
440449
ChildProcessSpawner.makeHandle({
441450
pid: ChildProcessSpawner.ProcessId(2),
@@ -465,6 +474,8 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
465474
mode: "dev",
466475
port: undefined,
467476
share: true,
477+
built: input.built ?? false,
478+
host: input.host,
468479
}).pipe(
469480
Effect.provide(Layer.mergeAll(emptyConfigLayer, netServiceLayer, spawnerLayer)),
470481
Effect.provideService(HostProcess.Platform, "linux"),
@@ -476,15 +487,76 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
476487
),
477488
);
478489

479-
return captured;
490+
return { env: captured, vpArgs, tailscaleCalls };
480491
});
481492

482493
it.effect("keeps an explicit T3CODE_BUNDLED_DEV=0 opt-out", () =>
483494
Effect.gen(function* () {
484-
const env = yield* shareSpawnedEnv({ ambientBundledDev: "0" });
495+
const { env } = yield* shareSpawned({ ambientBundledDev: "0" });
485496
assert.equal(env?.T3CODE_BUNDLED_DEV, "0");
486497
}),
487498
);
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+
});
488560
});
489561

490562
it.effect("reports non-zero exits without manufacturing a cause", () => {

‎scripts/dev-runner.ts‎

Lines changed: 71 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,16 @@ const MODE_ARGS = {
8484
"dev:desktop": ["run", "--filter=@t3tools/desktop", "--filter=@t3tools/web", "dev"],
8585
} as const satisfies Record<string, ReadonlyArray<string>>;
8686

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+
8797
type DevMode = keyof typeof MODE_ARGS;
8898
/**
8999
* `role` matters because only the backend honours `--host`/`T3CODE_HOST`; the
@@ -184,6 +194,17 @@ export class DevRunnerHostNotProxiableError extends Schema.TaggedError<DevRunner
184194
}
185195
}
186196

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+
187208
const optionalStringConfig = (name: string): Config.Config<string | undefined> =>
188209
Config.String(name).pipe(
189210
Config.option,
@@ -659,6 +680,7 @@ interface DevRunnerCliInput {
659680
readonly dryRun: boolean;
660681
readonly share: boolean;
661682
readonly seed?: boolean | undefined;
683+
readonly built: boolean;
662684
readonly runArgs: ReadonlyArray<string>;
663685
}
664686

@@ -683,6 +705,10 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
683705
return yield* new DevRunnerHostNotProxiableError({ mode: input.mode, host: input.host });
684706
}
685707

708+
if (input.built && (input.mode !== "dev" || !input.share)) {
709+
return yield* new DevRunnerBuiltNeedsShareError({ mode: input.mode });
710+
}
711+
686712
const worktreePath = yield* resolveGitWorktreePath(yield* HostProcess.WorkingDirectory);
687713

688714
const { offset, source } = yield* resolveOffset({
@@ -743,6 +769,7 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
743769
}
744770

745771
const sharedWebPort = BASE_WEB_PORT + webOffset;
772+
let built = false;
746773
if (input.share) {
747774
if (input.mode === "dev:server") {
748775
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
755782
// process (and reboots), so the cleanup has to be registered atomically
756783
// with creating it. An interrupt landing in between would otherwise
757784
// 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+
),
768810
),
769-
),
770811
).pipe(
771812
Effect.tapError((error: DevShareError) =>
772813
Effect.logWarning(
@@ -792,14 +833,21 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
792833
if (input.devUrl === undefined) {
793834
env.VITE_DEV_SERVER_URL = shared.url;
794835
}
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.
800844
env.T3CODE_BUNDLED_DEV = "1";
801845
}
802846
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+
);
803851
}
804852
}
805853
}
@@ -812,7 +860,7 @@ export const runDevRunnerWithInput = Effect.fn("dev-runner.runDevRunnerWithInput
812860
env,
813861
});
814862

815-
const args = [...MODE_ARGS[input.mode], ...input.runArgs];
863+
const args = [...(built ? BUILT_DEV_ARGS : MODE_ARGS[input.mode]), ...input.runArgs];
816864
const spawnCommand = yield* resolveSpawnCommand("vp", args, { env });
817865
const processContext = {
818866
mode: input.mode,
@@ -920,6 +968,12 @@ const devRunnerCli = Command.make("dev-runner", {
920968
),
921969
Flag.withFallbackConfig(optionalBooleanConfig("T3CODE_DEV_SEED")),
922970
),
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+
),
923977
runArgs: Argument.String("run-arg").pipe(
924978
Argument.withDescription("Additional Vite+ run args (pass after `--`)."),
925979
Argument.variadic(),

‎scripts/lib/dev-share.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,8 +127,14 @@ export interface DevShareResult {
127127
readonly host: string;
128128
}
129129

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+
*/
130135
export const shareDevServer = Effect.fn("devShare.shareDevServer")(function* (input: {
131136
readonly webPort: number;
137+
readonly localTarget?: { readonly port: number; readonly host: string };
132138
}) {
133139
const status = yield* readTailscaleStatus.pipe(
134140
Effect.mapError((error) => new TailscaleUnavailableError({ cause: error })),
@@ -155,9 +161,9 @@ export const shareDevServer = Effect.fn("devShare.shareDevServer")(function* (in
155161
// first, so it only binds the IPv6 loopback and a 127.0.0.1 target has
156162
// nothing behind it (tailscale answers 502).
157163
yield* ensureTailscaleServe({
158-
localPort: input.webPort,
164+
localPort: input.localTarget?.port ?? input.webPort,
159165
servePort: input.webPort,
160-
localHost: "localhost",
166+
localHost: input.localTarget?.host ?? "localhost",
161167
}).pipe(
162168
Effect.mapError((error) => {
163169
const explanation = explainCommandFailure(error);

0 commit comments

Comments
 (0)