mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-16 21:08:38 +08:00
68ae6d1f1c
## Summary - Adds the generated `@stackframe/tanstack-start` workspace package registration. - Adds TanStack Start platform macros/dependencies to the SDK template and generator. - Adds TanStack Start cookie/token-store support plus the handler SSR guard needed by Start. ## Scope This intentionally excludes Dashboard V2 routes, hooks, components, app shell logic, and dashboard API type additions. Those stay in the existing dashboard PR/branch. ## Validation - `pnpm install --lockfile-only --ignore-scripts` - `pnpm install --ignore-scripts` - `pnpm -C packages/template lint src/components-page/stack-handler-client.tsx src/lib/cookie.ts src/lib/stack-app/apps/implementations/client-app-impl.ts` Package typecheck was attempted with `pnpm -C packages/template typecheck`, but the clean worktree lacks generated package declaration outputs for workspace dependencies such as `@stackframe/stack-shared` and `@stackframe/stack-ui`. Per repo instructions, package builds/codegen are not run by agents. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * TanStack Start integration: published SDK package, example demo app, dashboard onboarding flow, framework-aware CTAs/docs, and a TanStack-specific provider for client-only auth routes. * Improved client/server auth: safer runtime guards and consistent cookie/token-store behavior across SSR and client. * **Documentation** * New Integrations guide and expanded getting-started/setup docs with TanStack Start examples and env/key guidance. * **Chores** * Template, build, tooling, and demo config updates to support the new platform. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
167 lines
5.2 KiB
Plaintext
167 lines
5.2 KiB
Plaintext
---
|
|
title: TanStack Start
|
|
description: Add Stack Auth to a TanStack Start app.
|
|
---
|
|
|
|
<Info>
|
|
The `@stackframe/tanstack-start` package is currently alpha. Pin exact package versions before shipping production apps.
|
|
</Info>
|
|
|
|
TanStack Start is a full-stack React framework built on TanStack Router and Vite. Stack Auth's TanStack Start package provides the same auth components and hooks as the React SDK, with cookie handling wired for TanStack Start.
|
|
|
|
## Setup
|
|
|
|
<Steps>
|
|
<Step title="Create or open a TanStack Start app">
|
|
If you do not have a TanStack Start app yet, create one with the TanStack CLI:
|
|
|
|
```bash title="Terminal"
|
|
npx @tanstack/cli@latest create
|
|
```
|
|
|
|
TanStack also publishes official examples if you prefer to start from a working project.
|
|
</Step>
|
|
|
|
<Step title="Install Stack Auth">
|
|
Install the alpha TanStack Start package:
|
|
|
|
```bash title="Terminal"
|
|
npm install @stackframe/tanstack-start
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Create Stack Auth keys">
|
|
In the [Stack Auth dashboard](https://app.stack-auth.com/projects), create a project and add these variables to your TanStack Start environment:
|
|
|
|
```bash title=".env"
|
|
VITE_STACK_PROJECT_ID=<your-project-id>
|
|
STACK_SECRET_SERVER_KEY=<your-secret-server-key>
|
|
```
|
|
|
|
Keep `STACK_SECRET_SERVER_KEY` server-only. Do not expose it to client code.
|
|
</Step>
|
|
|
|
<Step title="Create a Stack client app">
|
|
Create a Stack client app with cookie storage:
|
|
|
|
```ts title="src/stack/client.ts"
|
|
import { StackClientApp } from "@stackframe/tanstack-start";
|
|
|
|
export const stackClientApp = new StackClientApp({
|
|
projectId: import.meta.env.VITE_STACK_PROJECT_ID,
|
|
tokenStore: "cookie",
|
|
redirectMethod: "window",
|
|
});
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Wrap the root route">
|
|
Add `StackProvider` and `StackTheme` around your route outlet:
|
|
|
|
```tsx title="src/routes/__root.tsx"
|
|
import { StackProvider, StackTheme } from "@stackframe/tanstack-start";
|
|
import { createRootRoute, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
|
|
import { stackClientApp } from "../stack/client";
|
|
|
|
export const Route = createRootRoute({
|
|
component: RootComponent,
|
|
shellComponent: RootDocument,
|
|
});
|
|
|
|
function RootComponent() {
|
|
return (
|
|
<StackProvider app={stackClientApp}>
|
|
<StackTheme>
|
|
<Outlet />
|
|
</StackTheme>
|
|
</StackProvider>
|
|
);
|
|
}
|
|
|
|
function RootDocument({ children }: { children: React.ReactNode }) {
|
|
return (
|
|
<html>
|
|
<head>
|
|
<HeadContent />
|
|
</head>
|
|
<body>
|
|
{children}
|
|
<Scripts />
|
|
</body>
|
|
</html>
|
|
);
|
|
}
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Add the auth handler route">
|
|
Create a splat route at `/handler/*` for Stack Auth's built-in pages:
|
|
|
|
```tsx title="src/routes/handler/$.tsx"
|
|
import { StackHandler } from "@stackframe/tanstack-start";
|
|
import { createFileRoute, useLocation } from "@tanstack/react-router";
|
|
|
|
export const Route = createFileRoute("/handler/$")({
|
|
ssr: false,
|
|
component: HandlerPage,
|
|
});
|
|
|
|
function HandlerPage() {
|
|
const { pathname } = useLocation();
|
|
return <StackHandler fullPage location={pathname} />;
|
|
}
|
|
```
|
|
</Step>
|
|
|
|
<Step title="Use auth in routes">
|
|
Use Stack hooks from inside components rendered under the provider:
|
|
|
|
```tsx title="src/routes/index.tsx"
|
|
import { useUser } from "@stackframe/tanstack-start";
|
|
import { createFileRoute, Link } from "@tanstack/react-router";
|
|
|
|
export const Route = createFileRoute("/")({
|
|
component: HomePage,
|
|
});
|
|
|
|
function HomePage() {
|
|
const user = useUser();
|
|
|
|
if (!user) {
|
|
return <Link to="/handler/sign-in">Sign in</Link>;
|
|
}
|
|
|
|
return <div>Signed in as {user.primaryEmail}</div>;
|
|
}
|
|
```
|
|
|
|
Routes that use browser redirects should render on the client:
|
|
|
|
```tsx title="src/routes/protected.tsx"
|
|
import { useUser } from "@stackframe/tanstack-start";
|
|
import { createFileRoute } from "@tanstack/react-router";
|
|
|
|
export const Route = createFileRoute("/protected")({
|
|
ssr: false,
|
|
component: ProtectedPage,
|
|
});
|
|
|
|
function ProtectedPage() {
|
|
const user = useUser({ or: "redirect" });
|
|
return <div>Welcome, {user.primaryEmail}</div>;
|
|
}
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Notes
|
|
|
|
- The handler route must stay under the same origin as your app when using `tokenStore: "cookie"`.
|
|
- Render the handler route on the client (`ssr: false`) because built-in auth pages read browser location state.
|
|
- Render routes that rely on `useUser({ or: "redirect" })` on the client (`ssr: false`) when using `redirectMethod: "window"`.
|
|
- Use `redirectMethod: "window"` unless you explicitly wire a TanStack Router navigation adapter.
|
|
- If you change auth routes, configure the matching `urls` on `StackClientApp`.
|
|
- For server-only logic, use TanStack Start server functions and keep `STACK_SECRET_SERVER_KEY` out of client modules.
|
|
|
|
For TanStack Start framework details, see the [TanStack Start quick start](https://tanstack.com/start/latest/docs/framework/react/quick-start) and [server functions guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions).
|