[Docs] First-class TanStack Start in AI setup prompts + clearer env-var guidance#1438
Merged
Merged
Conversation
…mpts - Stress that STACK_PROJECT_ID (and STACK_SECRET_SERVER_KEY on the server) are the complete env-var set; there is no separate publishable/client key. - In the custom-page prompt, explain that overriding one handler URL doesn't override the others — every target falls back to urls.default and otherwise visibly redirects through <projectId>.built-with-stack-auth.com. - Document each handler URL target and the SDK call its custom page must invoke, plus the Trusted Domains whitelisting requirement.
Until now `mainType: "tanstack-start"` was routed through `@stackframe/react` and shared the React-only setup steps, which left agents guessing about 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: add `isDefinitelyTanstackStart`/`isMaybeTanstackStart` flags, switch the package map to `@stackframe/tanstack-start`, list TanStack Start alongside Next.js/React, and add three TanStack-specific steps: mounting `StackProvider`/`StackTheme` inside the root route's `component` (with `shellComponent` left untouched), wrapping `<Outlet />` in `Suspense`, and registering the `StackHandler` splat at `src/routes/handler/$.tsx` with `ssr: false`. Also surfaces the two TanStack notes that aren't obvious from the React docs: `routeTree.gen.ts` is generated and `useUser()` resolves the SSR user from TanStack Start's request cookies for free. - tanstack-start-demo: add paired `/ssr` and `/client` routes that render a shared `AuthDemoCard`, so the SSR-vs-`ssr: false` behavior is observable side-by-side. Drop the `ClientMountedUserButton` workaround in the header now that SSR cookie reading works, and replace the empty Suspense fallback with a `RouteLoadingState` skeleton. - Regenerate `docs-mintlify/guides/getting-started/setup.mdx` and `docs-mintlify/snippets/home-prompt-island.jsx` from the prompt. Co-authored-by: Cursor <cursoragent@cursor.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughAdds TanStack Start support to SDK prompts and generated docs, tightens cloud env-var guidance across framework tabs, and implements a TanStack Start demo app with new routes (/ssr, /client), components, and an updated root layout. ChangesTanStack Start Framework Support and Demo App
🎯 3 (Moderate) | ⏱️ ~25 minutes
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR improves Stack Auth's AI-assisted setup story across two areas: clearer environment-variable guidance (removing the phantom
Confidence Score: 5/5Safe to merge — all changes are documentation text and demo-app UI with no effect on SDK runtime behaviour. The changes touch only AI prompt text, auto-generated docs, and a demo application. The demo code is correct and clean. The one gap is that the Supabase section of the generated docs files wasn’t regenerated after the source was fixed, leaving a stale env-var name in those files — but this is documentation-only and does not affect any running code. docs-mintlify/snippets/home-prompt-island.jsx and docs-mintlify/guides/getting-started/setup.mdx — the Supabase env-var block in these generated files needs a fresh regeneration run to pick up the fix already present in prompts.ts. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[prompts.ts] -->|generate script| B[setup.mdx]
A -->|generate script| C[home-prompt-island.jsx]
A --> D[SDK section: TanStack Start added]
A --> E[Supabase section: source fixed]
D -->|regenerated correctly| B
D -->|regenerated correctly| C
E -->|NOT regenerated| F[Stale output: phantom key still present]
F --> B
F --> C
Prompt To Fix All With AIFix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
docs-mintlify/snippets/home-prompt-island.jsx:3
**Supabase env-var block still prescribes the non-existent publishable client key**
The source `supabaseSetupPrompt` in `prompts.ts` has been correctly updated (it now lists only `NEXT_PUBLIC_STACK_PROJECT_ID` and `STACK_SECRET_SERVER_KEY`), but the generation script wasn't re-run after that change. As a result, the Supabase section in both generated files still renders `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY` in the `.env.local` block — directly contradicting the "there is no separate publishable / client key" warnings added elsewhere in the same generated string. An AI agent reading the combined prompt will encounter the correct guidance in the SDK section and the incorrect guidance in the Supabase section on the same page. Running `scripts/generate-setup-prompt-docs.ts` again should fix this.
Reviews (2): Last reviewed commit: "[Docs] Update environment variable docum..." | Re-trigger Greptile |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
packages/stack-shared/src/interface/page-component-versions.ts (1)
116-116: 💤 Low valueConsider adding the specific SDK call for consistency.
While the description "Complete the magic-link exchange" is accurate, other table entries explicitly name the SDK method (e.g., line 114 specifies
callOAuthCallback(), line 115 specifiessignOut()). For consistency and to make the table a better quick-reference, consider:-| \`magicLinkCallback\` | Complete the magic-link exchange when the link is opened directly (separate from the OTP flow inside the sign-in page). | +| \`magicLinkCallback\` | On mount, call \`await stackApp.signInWithMagicLink(code)\` after user confirmation (separate from the OTP flow inside the sign-in page). |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/stack-shared/src/interface/page-component-versions.ts` at line 116, Update the table entry for `magicLinkCallback` so it names the exact SDK method used to complete the magic-link exchange (matching the style of the other entries that list `callOAuthCallback()` and `signOut()`); locate the `magicLinkCallback` description and append the actual SDK call name (for example, the method on our auth client that performs the exchange—replace the example with the real method in the SDK) so the table is a consistent quick-reference.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/stack-shared/src/ai/prompts.ts`:
- Around line 568-577: The doc text is contradictory about env var names: update
the wording around the STACK_PROJECT_ID / STACK_SECRET_SERVER_KEY example to
clearly state that server SDKs read unprefixed names (STACK_PROJECT_ID and
STACK_SECRET_SERVER_KEY) while client-side frameworks must use their publishable
prefixes (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
for Vite); replace the literal example that shows only STACK_PROJECT_ID with a
dual example or explanatory line showing both server and client variants, and
explicitly state that STACK_SECRET_SERVER_KEY must never be prefixed or exposed
to the client.
In `@packages/stack-shared/src/interface/page-component-versions.ts`:
- Line 115: The table entry for `signOut` and the signOut example are
inconsistent: the table instructs calling `stackApp.signOut()` then
`stackApp.redirectToAfterSignOut({ replace: true })`, while the example uses
`use(cacheSignOut(user))` calling `user.signOut()` and the button triggers
`stackApp.redirectToHome()`. Pick one pattern and make both consistent; either
update the table text to describe the example flow (mention
`use(cacheSignOut(user))`, `user.signOut()`, and `stackApp.redirectToHome()`),
or update the example to use the table-preferred APIs (`stackApp.signOut()` and
`stackApp.redirectToAfterSignOut({ replace: true })`) so the names
`stackApp.signOut`, `stackApp.redirectToAfterSignOut`,
`use(cacheSignOut(user))`, `user.signOut`, and `stackApp.redirectToHome` match
across docs.
---
Nitpick comments:
In `@packages/stack-shared/src/interface/page-component-versions.ts`:
- Line 116: Update the table entry for `magicLinkCallback` so it names the exact
SDK method used to complete the magic-link exchange (matching the style of the
other entries that list `callOAuthCallback()` and `signOut()`); locate the
`magicLinkCallback` description and append the actual SDK call name (for
example, the method on our auth client that performs the exchange—replace the
example with the real method in the SDK) so the table is a consistent
quick-reference.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f1cc97e7-b848-4fe8-916c-704c9bec2085
📒 Files selected for processing (11)
docs-mintlify/guides/getting-started/setup.mdxdocs-mintlify/snippets/home-prompt-island.jsxexamples/tanstack-start-demo/src/components/auth-demo-card.tsxexamples/tanstack-start-demo/src/components/header.tsxexamples/tanstack-start-demo/src/routeTree.gen.tsexamples/tanstack-start-demo/src/routes/__root.tsxexamples/tanstack-start-demo/src/routes/client.tsxexamples/tanstack-start-demo/src/routes/index.tsxexamples/tanstack-start-demo/src/routes/ssr.tsxpackages/stack-shared/src/ai/prompts.tspackages/stack-shared/src/interface/page-component-versions.ts
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Stack Auth’s AI-generated setup prompts and related documentation to (a) clarify which environment variables are required in cloud-project setups and (b) add first-class setup guidance for TanStack Start, plus a TanStack Start demo illustrating SSR vs client-only auth resolution.
Changes:
- Update the AI setup prompt to treat TanStack Start as a distinct framework and install
@stackframe/tanstack-startwith framework-specific integration steps. - Refine cloud-project env-var guidance in prompts and regenerate the Mintlify docs/snippets from the updated prompt source.
- Enhance the TanStack Start demo with
/ssrand/clientroutes and a sharedAuthDemoCardto compare SSR vsssr: false.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/stack-shared/src/interface/page-component-versions.ts | Adds a detailed warning/note about URL target overrides and hosted-handler redirects. |
| packages/stack-shared/src/ai/prompts.ts | Adds TanStack Start as a first-class framework and revises env-var guidance in the cloud-project flow. |
| examples/tanstack-start-demo/src/routeTree.gen.ts | Regenerates route tree to include new demo routes. |
| examples/tanstack-start-demo/src/routes/ssr.tsx | Adds SSR-enabled demo route using useUser() to resolve during server render. |
| examples/tanstack-start-demo/src/routes/client.tsx | Adds client-only (ssr: false) demo route for comparison. |
| examples/tanstack-start-demo/src/routes/index.tsx | Adds navigation links to the new SSR/client demo routes. |
| examples/tanstack-start-demo/src/routes/__root.tsx | Improves Suspense fallback UX via a skeleton loading state and refactors layout shell. |
| examples/tanstack-start-demo/src/components/header.tsx | Simplifies header user button rendering and adds links to demo routes. |
| examples/tanstack-start-demo/src/components/auth-demo-card.tsx | Introduces reusable card UI to display resolved user state and the corresponding snippet. |
| docs-mintlify/snippets/home-prompt-island.jsx | Regenerated setup prompt snippet to include TanStack Start + updated env-var guidance. |
| docs-mintlify/guides/getting-started/setup.mdx | Regenerated setup guide content to include TanStack Start + updated env-var guidance. |
Comments suppressed due to low confidence (1)
packages/stack-shared/src/ai/prompts.ts:577
- The cloud-project Backend env-var section states the SDK reads exactly two variables and that a third slot in .env.local is “wrong”, but the SDK supports (and reads) publishable client key env vars too (NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY / STACK_PUBLISHABLE_CLIENT_KEY) and some tooling/docs in this repo still rely on them. If the intent is “you can omit it by default”, the wording should be adjusted to avoid claiming the variable doesn’t exist / is never used.
\`\`\`.env .env.local
# Prefix STACK_PROJECT_ID with your framework's convention for client-exposed
# variables (e.g. NEXT_PUBLIC_STACK_PROJECT_ID for Next.js, VITE_STACK_PROJECT_ID
# for Vite). STACK_SECRET_SERVER_KEY must NEVER be exposed to the client and
# must NOT be prefixed.
STACK_PROJECT_ID=<your-project-id>
STACK_SECRET_SERVER_KEY=<your-secret-server-key>
\`\`\`
These two variables are the **complete** set the SDK reads in the cloud-project setup. Do not add any additional Stack Auth env vars (in particular, there is **no** separate publishable / client key — the project ID alone is sufficient on the client). The dashboard "Project Keys" page exposes exactly these two values; if a third slot is present in any \`.env.local\` you write, it is wrong.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Added clarifications regarding the usage of `NEXT_PUBLIC_STACK_PROJECT_ID` for client-exposed variables and emphasized that `STACK_SECRET_SERVER_KEY` must never be exposed to the client. - Updated the custom page prompt to specify that the project ID is the only client-exposed variable and detailed the handling of SDK calls for different frameworks, including TanStack Start. - Enhanced the explanation of the complete set of environment variables required for SDK setup, ensuring users understand the correct configuration without additional keys.
Collaborator
Author
|
@greptile-ai review |
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
nams1570
approved these changes
May 19, 2026
Collaborator
nams1570
left a comment
nams1570
left a comment
There was a problem hiding this comment.
Looks good, check bot comments. I think it does pay to be aggressive about making sure prompot doesn't put up the publishable client key
- Updated the setup documentation for Stack Auth, ensuring consistency across guides and snippets. - Enhanced instructions for installing SDKs, emphasizing the correct packages for various frameworks, including Next.js, React, and TanStack Start. - Clarified the process for initializing Stack App objects and setting up environment variables, particularly for frontend and backend configurations. - Regenerated `setup.mdx` and `home-prompt-island.jsx` to reflect the latest changes in the setup prompts.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-mintlify/guides/getting-started/setup.mdx`:
- Around line 638-643: Update the copyable env var lines in the
framework-specific code blocks so they use the framework-prefixed names instead
of the generic STACK_PROJECT_ID; e.g., in Next.js tabs change the literal line
to use NEXT_PUBLIC_STACK_PROJECT_ID, in Vite tabs use VITE_STACK_PROJECT_ID (and
similarly for any other framework-specific tabs referenced at the other
locations). Locate the occurrences that show the comment guidance and the
copyable line (the symbol STACK_PROJECT_ID in the current diff) and replace only
the copyable variable name to match the comment's recommended prefix while
leaving surrounding explanatory text intact.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9e5fd4d0-5b16-44f4-b76e-ba70ef72a049
📒 Files selected for processing (2)
docs-mintlify/guides/getting-started/setup.mdxdocs-mintlify/snippets/home-prompt-island.jsx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs-mintlify/snippets/home-prompt-island.jsx
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs-mintlify/guides/getting-started/setup.mdx (1)
646-651:⚠️ Potential issue | 🟠 Major | ⚡ Quick winUse framework-specific env-var names in the copyable .env lines.
In framework-specific tabs (Next.js, React, TanStack Start, etc.), the copyable environment variable lines still show the generic unprefixed
STACK_PROJECT_ID=<your-project-id>, even though the comments instruct users to add the framework's prefix. This leads to broken client config when users copy-paste the code verbatim.The Supabase tab (lines 1980-1985) demonstrates the correct pattern:
NEXT_PUBLIC_STACK_PROJECT_ID=<your-stack-project-id>Apply the same approach to frontend env-var blocks in other framework-specific tabs:
- Next.js (line 650):
NEXT_PUBLIC_STACK_PROJECT_ID=<your-project-id>- React/Vite (line 846):
VITE_STACK_PROJECT_ID=<your-project-id>(if Vite-based)- TanStack Start (line 1266):
VITE_STACK_PROJECT_ID=<your-project-id>(verify prefix)- Generic JS/TS (line 1074): Can remain
STACK_PROJECT_IDas fallbackSince this file is auto-generated from
packages/stack-shared/src/ai/prompts.ts, the fix should be applied in the prompt generator and this file regenerated.Also applies to: 842-847, 1070-1075, 1262-1267
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs-mintlify/guides/getting-started/setup.mdx` around lines 646 - 651, The copyable .env lines are using the generic STACK_PROJECT_ID instead of framework-specific names; update the prompt generator in packages/stack-shared/src/ai/prompts.ts to emit framework-specific env keys based on the tab (e.g., use NEXT_PUBLIC_STACK_PROJECT_ID for Next.js tabs, VITE_STACK_PROJECT_ID for Vite/React/TanStack Start tabs, and leave STACK_PROJECT_ID only for the generic JS/TS tab), update the template mapping or switch that builds those code blocks (look for the template variables or functions that render the Next.js, React/Vite, TanStack Start, and Supabase snippets), and then regenerate docs so the copyable blocks show NEXT_PUBLIC_STACK_PROJECT_ID, VITE_STACK_PROJECT_ID, etc., matching the comments in the file.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-mintlify/guides/getting-started/setup.mdx`:
- Around line 1262-1267: The example env variable in the TanStack Start section
uses STACK_PROJECT_ID but TanStack Start runs on Vite; update the example to use
the Vite client-exposed name by replacing the CONFIG line that sets
STACK_PROJECT_ID with VITE_STACK_PROJECT_ID=<your-project-id> (reference the
example line and the surrounding comment about Vite and the TanStack Start demo
which uses import.meta.env.VITE_STACK_PROJECT_ID).
---
Duplicate comments:
In `@docs-mintlify/guides/getting-started/setup.mdx`:
- Around line 646-651: The copyable .env lines are using the generic
STACK_PROJECT_ID instead of framework-specific names; update the prompt
generator in packages/stack-shared/src/ai/prompts.ts to emit framework-specific
env keys based on the tab (e.g., use NEXT_PUBLIC_STACK_PROJECT_ID for Next.js
tabs, VITE_STACK_PROJECT_ID for Vite/React/TanStack Start tabs, and leave
STACK_PROJECT_ID only for the generic JS/TS tab), update the template mapping or
switch that builds those code blocks (look for the template variables or
functions that render the Next.js, React/Vite, TanStack Start, and Supabase
snippets), and then regenerate docs so the copyable blocks show
NEXT_PUBLIC_STACK_PROJECT_ID, VITE_STACK_PROJECT_ID, etc., matching the comments
in the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4bceea3b-cbcf-4463-81f5-1ac48d726e35
📒 Files selected for processing (3)
docs-mintlify/guides/getting-started/setup.mdxdocs-mintlify/snippets/home-prompt-island.jsxpackages/stack-shared/src/ai/prompts.ts
✅ Files skipped from review due to trivial changes (1)
- docs-mintlify/snippets/home-prompt-island.jsx
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/stack-shared/src/ai/prompts.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_IDshould be prefixed via a generic "if available, prefix with your framework's convention" comment, and the backend section additionally listedNEXT_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:
NEXT_PUBLIC_STACK_PROJECT_ID, Vite →VITE_STACK_PROJECT_ID, etc.) is given inline.STACK_PROJECT_ID+STACK_SECRET_SERVER_KEY); a third slot in.env.localis wrong.2. First-class TanStack Start support (new commit)
Until now
mainType: "tanstack-start"was silently routed through@stackframe/reactand inherited the React-only setup steps. Agents had to guess at the TanStack-specific bits (where to mountStackProvider, what to do withrouteTree.gen.ts, howuseUser()behaves under SSR, where the handler route lives).prompts.tsnow:mainTypeand routes the install to@stackframe/tanstack-start.StackProvider/StackThemeinside the root route'scomponent(the inner React tree), keepingshellComponentas the document shell.<Outlet />inSuspenseinsideRootComponent.src/routes/handler/\$.tsxwithssr: false.routeTree.gen.tsis generated and shouldn't be hand-edited, anduseUser()resolves the SSR user from TanStack Start's request cookies for free as long astokenStore: \"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 (
/ssrand/client) render the sameAuthDemoCardso 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
Made with Cursor
Summary by CodeRabbit
New Features
Documentation
Improvements