feat: add React Refresh plugin to TanStack Start configurations and introduce SecretLeakButton component for error testing

Author: yamcodes

apps/playgrounds/tanstack-start/src/components/secret-leak-button.tsx

@@ -0,0 +1,21 @@
+import { useState } from "react";
+import { env } from "~/env";
+
+function LeakedSecret() {
+	// Accessing server-only DATABASE_URL directly in client render tree throws an error
+	return <p>Server key leaked: {env.DATABASE_URL}</p>;
+}
+
+export function SecretLeakButton() {
+	const [attempted, setAttempted] = useState(false);
+
+	if (attempted) {
+		return <LeakedSecret />;
+	}
+
+	return (
+		<button type="button" onClick={() => setAttempted(true)}>
+			Try reading DATABASE_URL on the client
+		</button>
+	);
+}

apps/playgrounds/tanstack-start/src/routes/index.tsx

@@ -1,7 +1,7 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
-import { useState } from "react";
-import { env } from "../env";
+import { SecretLeakButton } from "~/components/secret-leak-button";
+import { env } from "~/env";
 
 const getDatabaseHost = createServerFn({ method: "GET" }).handler(() => {
 	// Server functions can safely read server secrets without leaking them to the client:
@@ -14,30 +14,15 @@ export const Route = createFileRoute("/")({
 	loader: () => getDatabaseHost(),
 });
 
-function tryReadServerKeyOnClient(): string {
-	try {
-		return `Server key leaked: ${env.DATABASE_URL}`;
-	} catch (error) {
-		return error instanceof Error ? error.message : String(error);
-	}
-}
-
 function Home() {
 	const dbHost = Route.useLoaderData();
-	const [clientReadResult, setClientReadResult] = useState<string | null>(null);
 
 	return (
 		<main style={{ fontFamily: "system-ui, sans-serif", padding: "2rem" }}>
 			<h1>API: {env.VITE_API_URL}</h1>
 			<p>Public key inlined into the client bundle: {env.VITE_API_URL}</p>
 			<p>Database host loaded through createServerFn: {dbHost}</p>
-			<button
-				type="button"
-				onClick={() => setClientReadResult(tryReadServerKeyOnClient())}
-			>
-				Try reading DATABASE_URL on the client
-			</button>
-			{clientReadResult ? <p>{clientReadResult}</p> : null}
+			<SecretLeakButton />
 		</main>
 	);
 }

apps/playgrounds/tanstack-start/tsconfig.json

@@ -1,6 +1,9 @@
 {
 	"include": ["**/*.ts", "**/*.tsx", "**/*.d.ts"],
 	"compilerOptions": {
+		"paths": {
+			"~/*": ["./src/*"]
+		},
 		"strict": true,
 		"esModuleInterop": true,
 		"jsx": "react-jsx",

apps/playgrounds/tanstack-start/vite.config.ts

@@ -4,6 +4,9 @@ import viteReact from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
 export default defineConfig({
+	resolve: {
+		tsconfigPaths: true,
+	},
 	server: {
 		port: 3000,
 	},

apps/www/content/docs/frameworks/tanstack-start.mdx

@@ -95,6 +95,12 @@ Install `@vitejs/plugin-react` if it is not already a dependency. If you
 aren't using ArkType, import the ArkEnv plugin from
 `@arkenv/vite-plugin/standard`.
 
+:::warning[React Refresh plugin required for client hydration]
+TanStack Start React dev mode requires the React Refresh runtime (`/@react-refresh`). You must include `@vitejs/plugin-react` (or `@vitejs/plugin-react-swc`) in your Vite `plugins` array and place it **after** `tanstackStart()`.
+
+If the React plugin is missing, Vite fails to load the client entry (`/@react-refresh could not be resolved`). The page will still render via SSR, but client-side hydration fails, leaving interactive handlers (like `onClick` listeners) unattached.
+:::
+
 ### Define your schema
 
 Create an `env.ts` file in your source tree. Keys your client bundle reads must

arkenv.code-workspace

@@ -99,6 +99,10 @@
 			"path": "apps/playgrounds/solid-start",
 			"name": "🛝 solid-start"
 		},
+		{
+			"path": "apps/playgrounds/tanstack-start",
+			"name": "🛝 tanstack-start"
+		},
 		{
 			"path": "apps/playgrounds/bun-react",
 			"name": "🛝 bun-react"
@@ -163,6 +167,10 @@
 			"path": "examples/with-solid-start",
 			"name": "💡 with-solid-start"
 		},
+		{
+			"path": "examples/with-tanstack-start",
+			"name": "💡 with-tanstack-start"
+		},
 		{
 			"path": "examples/with-zod",
 			"name": "💡 with-zod"

examples/with-tanstack-start/src/components/secret-leak-button.tsx

@@ -0,0 +1,21 @@
+import { useState } from "react";
+import { env } from "../env";
+
+function LeakedSecret() {
+	// Accessing server-only DATABASE_URL directly in client render tree throws an error
+	return <p>Server key leaked: {env.DATABASE_URL}</p>;
+}
+
+export function SecretLeakButton() {
+	const [attempted, setAttempted] = useState(false);
+
+	if (attempted) {
+		return <LeakedSecret />;
+	}
+
+	return (
+		<button type="button" onClick={() => setAttempted(true)}>
+			Try reading DATABASE_URL on the client
+		</button>
+	);
+}

examples/with-tanstack-start/src/routes/index.tsx

@@ -1,6 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
-import { useState } from "react";
+import { SecretLeakButton } from "../components/secret-leak-button";
 import { env } from "../env";
 
 const getDatabaseHost = createServerFn({ method: "GET" }).handler(() => {
@@ -14,30 +14,15 @@ export const Route = createFileRoute("/")({
 	loader: () => getDatabaseHost(),
 });
 
-function tryReadServerKeyOnClient(): string {
-	try {
-		return `Server key leaked: ${env.DATABASE_URL}`;
-	} catch (error) {
-		return error instanceof Error ? error.message : String(error);
-	}
-}
-
 function Home() {
 	const dbHost = Route.useLoaderData();
-	const [clientReadResult, setClientReadResult] = useState<string | null>(null);
 
 	return (
 		<main style={{ fontFamily: "system-ui, sans-serif", padding: "2rem" }}>
 			<h1>API: {env.VITE_API_URL}</h1>
 			<p>Public key inlined into the client bundle: {env.VITE_API_URL}</p>
 			<p>Database host loaded through createServerFn: {dbHost}</p>
-			<button
-				type="button"
-				onClick={() => setClientReadResult(tryReadServerKeyOnClient())}
-			>
-				Try reading DATABASE_URL on the client
-			</button>
-			{clientReadResult ? <p>{clientReadResult}</p> : null}
+			<SecretLeakButton />
 		</main>
 	);
 }