[Docs] First-class TanStack Start in AI setup prompts + clearer env-var guidance (#1438)

## Summary

Two related improvements to Stack Auth's AI setup story, both driven by
`packages/stack-shared/src/ai/prompts.ts`:

### 1. Clearer env-var guidance in the cloud-project flow (existing
commit)

The previous wording suggested `STACK_PROJECT_ID` should be prefixed via
a generic _"if available, prefix with your framework's convention"_
comment, and the backend section additionally listed
`NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY` — which the SDK does not
actually read in the cloud-project setup. Agents would dutifully
fabricate that third variable.

This is now spelled out:
- The exact prefix per framework (Next.js →
`NEXT_PUBLIC_STACK_PROJECT_ID`, Vite → `VITE_STACK_PROJECT_ID`, etc.) is
given inline.
- A note clarifies that on the client, **only** the project ID is read —
there is no separate publishable / client key.
- A note clarifies that the backend setup reads exactly two variables
(`STACK_PROJECT_ID` + `STACK_SECRET_SERVER_KEY`); a third slot in
`.env.local` is wrong.

### 2. First-class TanStack Start support (new commit)

Until now `mainType: "tanstack-start"` was silently routed through
`@stackframe/react` and inherited the React-only setup steps. Agents had
to guess at the TanStack-specific bits (where to mount `StackProvider`,
what to do with `routeTree.gen.ts`, how `useUser()` behaves under SSR,
where the handler route lives).

`prompts.ts` now:
- Recognizes TanStack Start as its own `mainType` and routes the install
to `@stackframe/tanstack-start`.
- Lists TanStack Start alongside Next.js / React in the
supported-frameworks list and the package table.
- Adds three TanStack-specific steps that don't apply to vanilla React:
1. Mount `StackProvider` / `StackTheme` inside the root route's
`component` (the inner React tree), keeping `shellComponent` as the
document shell.
  2. Wrap `<Outlet />` in `Suspense` inside `RootComponent`.
3. Register the Stack handler splat at `src/routes/handler/\$.tsx` with
`ssr: false`.
- Surfaces the two notes that aren't obvious from the React docs:
`routeTree.gen.ts` is generated and shouldn't be hand-edited, and
`useUser()` resolves the SSR user from TanStack Start's request cookies
for free as long as `tokenStore: \"cookie\"` is set.

The auto-generated outputs
(`docs-mintlify/guides/getting-started/setup.mdx`,
`docs-mintlify/snippets/home-prompt-island.jsx`) are regenerated from
the prompt.

### 3. tanstack-start-demo SSR-vs-client examples

Two paired routes (`/ssr` and `/client`) render the same `AuthDemoCard`
so the SSR-vs-\`ssr: false\` tradeoff is observable side-by-side. The
new \`AuthDemoCard\` shows the resolved Stack Auth user (or sign-in/up
buttons) plus the snippet that produced it. The
\`ClientMountedUserButton\` workaround in the header is dropped now that
SSR cookie reading just works, and the empty \`Suspense
fallback={null}\` in \`__root.tsx\` is replaced with a
\`RouteLoadingState\` skeleton.

## Test plan

- [ ] \`pnpm typecheck\` and \`pnpm lint\` both pass on the touched
packages (\`stack-shared\`, \`tanstack-start-demo\`).
- [ ] \`docs-mintlify/guides/getting-started/setup.mdx\` and
\`docs-mintlify/snippets/home-prompt-island.jsx\` are byte-identical to
a fresh \`scripts/generate-setup-prompt-docs.ts\` run.
- [ ] In \`tanstack-start-demo\`, \`/ssr\` renders the user card during
the server response (no flash from signed-out → signed-in), and
\`/client\` renders the empty card on first paint, then resolves to the
user after hydration.
- [ ] \`/handler/sign-in\`, \`/handler/sign-up\`, OAuth callbacks, and
password reset all render correctly through the new splat route.
- [ ] Following the new TanStack Start prompt steps from scratch in an
empty \`npm create @tanstack/start@latest\` project produces a working
sign-in flow without any extra changes.

Made with [Cursor](https://cursor.com)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added TanStack Start support, provider/theme wiring, SSR and
client-only demo pages, plus an Auth demo card component.

* **Documentation**
* Updated setup guides and snippets across frameworks; clarified env-var
guidance (client reads only project ID; secret is server-only) and
removed misleading publishable-key example.
  * Clarified OAuth callback and hosted-domain behavior.

* **Improvements**
* Added loading skeleton UI, refined demo navigation, and tightened
setup wording.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1438?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: mantrakp04

docs-mintlify/guides/getting-started/setup.mdx

@@ -0,0 +1,61 @@
+import { runAsynchronouslyWithAlert } from "@stackframe/stack-shared/dist/utils/promises";
+import { UserAvatar, useStackApp } from "@stackframe/tanstack-start";
+import type { CurrentUser } from "@stackframe/tanstack-start";
+
+type AuthDemoCardProps = {
+  title: string,
+  eyebrow: string,
+  description: string,
+  user: CurrentUser | null,
+  code: string,
+};
+
+export function AuthDemoCard(props: AuthDemoCardProps) {
+  const app = useStackApp();
+  const userLabel = props.user?.displayName ?? props.user?.primaryEmail ?? props.user?.id;
+
+  return (
+    <section className="grid w-full gap-6">
+      <div className="rounded-lg border border-zinc-200 bg-white p-8 shadow-sm dark:border-zinc-800 dark:bg-zinc-900">
+        <p className="mb-2 text-sm font-medium text-zinc-500 dark:text-zinc-400">{props.eyebrow}</p>
+        <h1 className="text-3xl font-semibold tracking-tight">{props.title}</h1>
+        <p className="mt-4 max-w-2xl text-zinc-600 dark:text-zinc-300">{props.description}</p>
+
+        <div className="mt-8 rounded-lg border border-zinc-200 p-5 dark:border-zinc-800">
+          {props.user ? (
+            <div className="flex flex-col gap-4 sm:flex-row sm:items-center">
+              <UserAvatar user={props.user} size={64} />
+              <div className="min-w-0">
+                <p className="text-sm text-zinc-500 dark:text-zinc-400">Resolved Stack Auth user</p>
+                <p className="truncate text-xl font-semibold">{userLabel}</p>
+                <p className="mt-1 break-all font-mono text-sm text-zinc-500 dark:text-zinc-400">{props.user.id}</p>
+              </div>
+            </div>
+          ) : (
+            <div>
+              <p className="text-lg font-semibold">No signed-in user</p>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+                This route rendered the signed-out branch from Stack Auth.
+              </p>
+              <div className="mt-4 flex flex-wrap gap-3">
+                <button className="rounded-md bg-zinc-950 px-4 py-2 text-sm font-medium text-white transition-colors hover:transition-none dark:bg-white dark:text-zinc-950" onClick={() => runAsynchronouslyWithAlert(app.redirectToSignIn())}>
+                  Sign in
+                </button>
+                <button className="rounded-md border border-zinc-300 px-4 py-2 text-sm font-medium transition-colors hover:bg-zinc-100 hover:transition-none dark:border-zinc-700 dark:hover:bg-zinc-800" onClick={() => runAsynchronouslyWithAlert(app.redirectToSignUp())}>
+                  Sign up
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+
+      <div className="rounded-lg border border-zinc-200 bg-zinc-950 p-5 text-zinc-100 shadow-sm dark:border-zinc-800">
+        <div className="mb-3 flex items-center justify-between gap-3">
+          <h2 className="text-sm font-semibold uppercase text-zinc-400">Usage snippet</h2>
+        </div>
+        <pre className="overflow-x-auto text-sm leading-6"><code>{props.code}</code></pre>
+      </div>
+    </section>
+  );
+}

docs-mintlify/snippets/home-prompt-island.jsx

@@ -1,6 +1,5 @@
 import { Link } from "@tanstack/react-router";
 import { UserButton } from "@stackframe/tanstack-start";
-import { useEffect, useState } from "react";
 
 export function Header() {
   return (
@@ -11,23 +10,20 @@ export function Header() {
             <Link to="/" className="font-semibold tracking-tight">
               Stack TanStack Demo
             </Link>
+            <Link to="/ssr" className="text-sm text-zinc-600 hover:text-zinc-950 hover:transition-none dark:text-zinc-300 dark:hover:text-white">
+              SSR
+            </Link>
+            <Link to="/client" className="text-sm text-zinc-600 hover:text-zinc-950 hover:transition-none dark:text-zinc-300 dark:hover:text-white">
+              Client
+            </Link>
             <Link to="/protected" className="text-sm text-zinc-600 hover:text-zinc-950 hover:transition-none dark:text-zinc-300 dark:hover:text-white">
               Protected
             </Link>
           </nav>
-          <ClientMountedUserButton />
+          <UserButton />
         </div>
       </header>
       <div className="h-14" />
     </>
   );
 }
-
-function ClientMountedUserButton() {
-  const [isMounted, setIsMounted] = useState(false);
-  useEffect(() => {
-    setIsMounted(true);
-  }, []);
-
-  return isMounted ? <UserButton /> : <div className="h-9 w-9" />;
-}

examples/tanstack-start-demo/src/components/auth-demo-card.tsx

@@ -9,15 +9,27 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as SsrRouteImport } from './routes/ssr'
 import { Route as ProtectedRouteImport } from './routes/protected'
+import { Route as ClientRouteImport } from './routes/client'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as HandlerSplatRouteImport } from './routes/handler/$'
 
+const SsrRoute = SsrRouteImport.update({
+  id: '/ssr',
+  path: '/ssr',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ProtectedRoute = ProtectedRouteImport.update({
   id: '/protected',
   path: '/protected',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ClientRoute = ClientRouteImport.update({
+  id: '/client',
+  path: '/client',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -31,43 +43,65 @@ const HandlerSplatRoute = HandlerSplatRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/client': typeof ClientRoute
   '/protected': typeof ProtectedRoute
+  '/ssr': typeof SsrRoute
   '/handler/$': typeof HandlerSplatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/client': typeof ClientRoute
   '/protected': typeof ProtectedRoute
+  '/ssr': typeof SsrRoute
   '/handler/$': typeof HandlerSplatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/client': typeof ClientRoute
   '/protected': typeof ProtectedRoute
+  '/ssr': typeof SsrRoute
   '/handler/$': typeof HandlerSplatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/protected' | '/handler/$'
+  fullPaths: '/' | '/client' | '/protected' | '/ssr' | '/handler/$'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/protected' | '/handler/$'
-  id: '__root__' | '/' | '/protected' | '/handler/$'
+  to: '/' | '/client' | '/protected' | '/ssr' | '/handler/$'
+  id: '__root__' | '/' | '/client' | '/protected' | '/ssr' | '/handler/$'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  ClientRoute: typeof ClientRoute
   ProtectedRoute: typeof ProtectedRoute
+  SsrRoute: typeof SsrRoute
   HandlerSplatRoute: typeof HandlerSplatRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/ssr': {
+      id: '/ssr'
+      path: '/ssr'
+      fullPath: '/ssr'
+      preLoaderRoute: typeof SsrRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/protected': {
       id: '/protected'
       path: '/protected'
       fullPath: '/protected'
       preLoaderRoute: typeof ProtectedRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/client': {
+      id: '/client'
+      path: '/client'
+      fullPath: '/client'
+      preLoaderRoute: typeof ClientRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -87,7 +121,9 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  ClientRoute: ClientRoute,
   ProtectedRoute: ProtectedRoute,
+  SsrRoute: SsrRoute,
   HandlerSplatRoute: HandlerSplatRoute,
 }
 export const routeTree = rootRouteImport

examples/tanstack-start-demo/src/components/header.tsx

@@ -44,15 +44,50 @@ function RootComponent() {
   return (
     <StackProvider app={stackApp}>
       <StackTheme>
-        <div className="min-h-screen bg-zinc-100 text-zinc-950 dark:bg-zinc-950 dark:text-zinc-50">
-          <Header />
-          <main className="mx-auto flex min-h-[calc(100vh-3.5rem)] max-w-5xl px-4 py-8">
-            <Suspense fallback={null}>
-              <Outlet />
-            </Suspense>
-          </main>
-        </div>
+        <AppShell>
+          <Suspense fallback={<RouteLoadingState />}>
+            <Outlet />
+          </Suspense>
+        </AppShell>
       </StackTheme>
     </StackProvider>
   );
 }
+
+function AppShell({ children }: { children: ReactNode }) {
+  return (
+    <div className="min-h-screen bg-zinc-100 text-zinc-950 dark:bg-zinc-950 dark:text-zinc-50">
+      <Header />
+      <main className="mx-auto flex min-h-[calc(100vh-3.5rem)] max-w-5xl px-4 py-8">
+        {children}
+      </main>
+    </div>
+  );
+}
+
+function RouteLoadingState() {
+  return (
+    <section className="grid w-full place-items-center">
+      <div className="w-full max-w-2xl rounded-lg border border-zinc-200 bg-white p-8 shadow-sm dark:border-zinc-800 dark:bg-zinc-900">
+        <div className="flex flex-col gap-5 sm:flex-row sm:items-center">
+          <div className="h-24 w-24 shrink-0 rounded-full bg-zinc-200 dark:bg-zinc-800" />
+          <div className="min-w-0 flex-1">
+            <div className="h-4 w-24 rounded bg-zinc-200 dark:bg-zinc-800" />
+            <div className="mt-3 h-9 w-full max-w-md rounded bg-zinc-200 dark:bg-zinc-800" />
+          </div>
+        </div>
+        <div className="mt-8 grid gap-3 text-sm">
+          <div className="grid gap-1 sm:grid-cols-[8rem_1fr]">
+            <div className="h-5 w-16 rounded bg-zinc-200 dark:bg-zinc-800" />
+            <div className="h-5 w-full rounded bg-zinc-200 dark:bg-zinc-800" />
+          </div>
+          <div className="grid gap-1 sm:grid-cols-[8rem_1fr]">
+            <div className="h-5 w-20 rounded bg-zinc-200 dark:bg-zinc-800" />
+            <div className="h-5 w-12 rounded bg-zinc-200 dark:bg-zinc-800" />
+          </div>
+        </div>
+        <div className="mt-8 h-9 w-20 rounded-md bg-zinc-200 dark:bg-zinc-800" />
+      </div>
+    </section>
+  );
+}

examples/tanstack-start-demo/src/routeTree.gen.ts

@@ -0,0 +1,38 @@
+import { useUser } from "@stackframe/tanstack-start";
+import { createFileRoute } from "@tanstack/react-router";
+import { AuthDemoCard } from "~/components/auth-demo-card";
+
+export const Route = createFileRoute("/client")({
+  ssr: false,
+  component: ClientAuthDemoPage,
+});
+
+const clientSnippet = `import { useUser } from "@stackframe/tanstack-start";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/client")({
+  ssr: false,
+  component: ClientAuthDemoPage,
+});
+
+function ClientAuthDemoPage() {
+  // This route is skipped during SSR. The user is resolved
+  // in the browser from the client token store.
+  const user = useUser({ includeRestricted: true });
+
+  return <div>{user?.displayName ?? "Signed out"}</div>;
+}`;
+
+function ClientAuthDemoPage() {
+  const user = useUser({ includeRestricted: true });
+
+  return (
+    <AuthDemoCard
+      eyebrow="Client-only route"
+      title="Stack Auth user fetched in the browser"
+      description="This route opts out of SSR with ssr: false. The UI is rendered on the client, and Stack Auth resolves the current user from the browser token store."
+      user={user}
+      code={clientSnippet}
+    />
+  );
+}

examples/tanstack-start-demo/src/routes/__root.tsx

@@ -1,6 +1,6 @@
 import { runAsynchronouslyWithAlert } from "@stackframe/stack-shared/dist/utils/promises";
 import { UserAvatar, useStackApp, useUser } from "@stackframe/tanstack-start";
-import { createFileRoute } from "@tanstack/react-router";
+import { Link, createFileRoute } from "@tanstack/react-router";
 
 export const Route = createFileRoute("/")({
   component: HomePage,
@@ -19,6 +19,14 @@ function HomePage() {
           <p className="mt-4 text-zinc-600 dark:text-zinc-300">
             This example uses <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-sm dark:bg-zinc-800">@stackframe/tanstack-start</code> with file-based routes and Stack Auth handler pages.
           </p>
+          <div className="mt-6 flex flex-wrap gap-3">
+            <Link to="/ssr" className="rounded-md border border-zinc-300 px-4 py-2 text-sm font-medium transition-colors hover:bg-zinc-100 hover:transition-none dark:border-zinc-700 dark:hover:bg-zinc-800">
+              SSR demo
+            </Link>
+            <Link to="/client" className="rounded-md border border-zinc-300 px-4 py-2 text-sm font-medium transition-colors hover:bg-zinc-100 hover:transition-none dark:border-zinc-700 dark:hover:bg-zinc-800">
+              Client demo
+            </Link>
+          </div>
           <div className="mt-6 flex flex-wrap gap-3">
             <button className="rounded-md bg-zinc-950 px-4 py-2 text-sm font-medium text-white transition-colors hover:transition-none dark:bg-white dark:text-zinc-950" onClick={() => runAsynchronouslyWithAlert(app.redirectToSignIn())}>
               Sign in
@@ -66,6 +74,12 @@ function HomePage() {
         </dl>
 
         <div className="mt-8 flex flex-wrap gap-3">
+          <Link to="/ssr" className="rounded-md border border-zinc-300 px-4 py-2 text-sm font-medium transition-colors hover:bg-zinc-100 hover:transition-none dark:border-zinc-700 dark:hover:bg-zinc-800">
+            SSR demo
+          </Link>
+          <Link to="/client" className="rounded-md border border-zinc-300 px-4 py-2 text-sm font-medium transition-colors hover:bg-zinc-100 hover:transition-none dark:border-zinc-700 dark:hover:bg-zinc-800">
+            Client demo
+          </Link>
           <button className="rounded-md bg-red-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-red-700 hover:transition-none" onClick={() => runAsynchronouslyWithAlert(app.redirectToSignOut())}>
             Sign out
           </button>

examples/tanstack-start-demo/src/routes/client.tsx

@@ -0,0 +1,36 @@
+import { useUser } from "@stackframe/tanstack-start";
+import { createFileRoute } from "@tanstack/react-router";
+import { AuthDemoCard } from "~/components/auth-demo-card";
+
+export const Route = createFileRoute("/ssr")({
+  component: SsrAuthDemoPage,
+});
+
+const ssrSnippet = `import { useUser } from "@stackframe/tanstack-start";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/ssr")({
+  component: SsrAuthDemoPage,
+});
+
+function SsrAuthDemoPage() {
+  // This hook can suspend during SSR while Stack Auth reads
+  // the TanStack Start request cookies and fetches the user.
+  const user = useUser({ includeRestricted: true });
+
+  return <div>{user?.displayName ?? "Signed out"}</div>;
+}`;
+
+function SsrAuthDemoPage() {
+  const user = useUser({ includeRestricted: true });
+
+  return (
+    <AuthDemoCard
+      eyebrow="SSR route"
+      title="Stack Auth user fetched during server render"
+      description="This route keeps SSR enabled. The Stack Auth hook can resolve the current user from TanStack Start request cookies while React renders the route on the server."
+      user={user}
+      code={ssrSnippet}
+    />
+  );
+}