[Docs] Clarify env vars and custom page URL overrides in AI setup prompts#1436
[Docs] Clarify env vars and custom page URL overrides in AI setup prompts#1436mantrakp04 wants to merge 1 commit into
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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughUpdated environment variable guidance and OAuth handler documentation across SDK setup prompts and auto-generated documentation. Frontend cloud deployments now explicitly describe framework-specific ChangesConfiguration and OAuth Guidance
🎯 2 (Simple) | ⏱️ ~8 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)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
docs-mintlify/snippets/home-prompt-island.jsxParsing error: The keyword 'export' is reserved docs-mintlify/guides/getting-started/setup.mdxParsing error: Assigning to rvalue packages/stack-shared/src/ai/prompts.tsParsing error: error TS5012: Cannot read file '/tsconfig.json': ENOENT: no such file or directory, open '/tsconfig.json'.
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 |
Greptile SummaryThis PR updates the Stack Auth AI setup prompts to clarify that only
Confidence Score: 3/5The core SDK guidance improvements are accurate, but the Supabase setup section was left with a contradictory third env-var entry that directly undermines the 'no publishable key' message this PR introduces. The Supabase
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[User visits auth flow URL] --> B{Is URL target customized?}
B -- Yes --> C[Render custom page at your origin]
C --> D{Which target?}
D -- signIn/signUp --> E[Render form, call stackApp.signIn/signUp]
D -- oauthCallback --> F[Call stackApp.callOAuthCallback]
D -- signOut --> G[Call stackApp.signOut + redirectToAfterSignOut]
D -- magicLinkCallback --> H[Complete magic-link exchange]
D -- other targets --> I[Implement per-target]
B -- No --> J[Redirect through projectId.built-with-stack-auth.com]
J --> K{Domain whitelisted?}
K -- Yes --> L[Hosted page serves request]
K -- No --> M[REDIRECT_URL_NOT_WHITELISTED error]
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | \`signIn\`, \`signUp\` | Render the forms described in this prompt (or its sign-in / sign-up counterpart). | | ||
| | \`oauthCallback\` | On mount, call \`await stackApp.callOAuthCallback()\`. The SDK exchanges the \`code\`/\`state\` query params for tokens and then redirects to \`afterSignIn\`. | | ||
| | \`signOut\` | On mount, call \`await stackApp.signOut()\` then \`await stackApp.redirectToAfterSignOut({ replace: true })\`. | | ||
| | \`magicLinkCallback\` | Complete the magic-link exchange when the link is opened directly (separate from the OTP flow inside the sign-in page). | |
There was a problem hiding this comment.
magicLinkCallback row missing its required SDK call
The oauthCallback row specifies await stackApp.callOAuthCallback() and the signOut row specifies await stackApp.signOut() / await stackApp.redirectToAfterSignOut(...). The magicLinkCallback row only says "Complete the magic-link exchange" without naming the SDK method to invoke on mount. Since this table is the primary guidance for AI agents implementing custom pages, the missing call will cause agents to either guess the API name or leave the page incomplete.
Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/stack-shared/src/interface/page-component-versions.ts
Line: 116
Comment:
**`magicLinkCallback` row missing its required SDK call**
The `oauthCallback` row specifies `await stackApp.callOAuthCallback()` and the `signOut` row specifies `await stackApp.signOut()` / `await stackApp.redirectToAfterSignOut(...)`. The `magicLinkCallback` row only says "Complete the magic-link exchange" without naming the SDK method to invoke on mount. Since this table is the primary guidance for AI agents implementing custom pages, the missing call will cause agents to either guess the API name or leave the page incomplete.
How can I resolve this? If you propose a fix, please make it concise.![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/stack-shared/src/ai/prompts.ts (2)
166-172:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winCritical inconsistency: Supabase example contradicts new env-var guidance.
The Supabase setup example still references
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, but the updated cloud-project setup instructions (lines 543, 570) now explicitly state there is no separate publishable/client key—onlySTACK_PROJECT_IDis needed on the client. This contradicts the new documentation and will confuse users.🔧 Proposed fix to align with new env-var guidance
Also add the Stack Auth environment variables: ```.env .env.local NEXT_PUBLIC_STACK_PROJECT_ID=<your-stack-project-id> - NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=<your-publishable-client-key> STACK_SECRET_SERVER_KEY=<your-secret-server-key> ```🤖 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/ai/prompts.ts` around lines 166 - 172, Update the Supabase setup example to remove the now-incorrect NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY and align it with the new env-var guidance by showing only the client-facing NEXT_PUBLIC_STACK_PROJECT_ID and the server secret STACK_SECRET_SERVER_KEY; specifically, edit the example block that currently lists NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY so it instead shows NEXT_PUBLIC_STACK_PROJECT_ID=<your-stack-project-id> and STACK_SECRET_SERVER_KEY=<your-secret-server-key>, ensuring the docs consistently reference NEXT_PUBLIC_STACK_PROJECT_ID (client) and STACK_SECRET_SERVER_KEY (server).
299-299:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winCritical inconsistency: CLI example contradicts new env-var guidance.
The CLI
prompt_cli_loginfunction signature includes apublishable_client_keyparameter, but the updated cloud-project setup instructions (lines 543, 570) now explicitly state there is no separate publishable/client key—only the project ID is needed on the client. This example contradicts the new documentation.🔧 Proposed fix to align with new env-var guidance
refresh_token = prompt_cli_login( app_url="https://your-app-url.example.com", project_id="your-project-id-here", - publishable_client_key="your-publishable-client-key-here", )Note: Verify that the CLI template implementation (
stack_auth_cli_template.py) no longer requires thepublishable_client_keyparameter. If the template still expects it, the template itself needs updating too.🤖 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/ai/prompts.ts` at line 299, The CLI example uses a now-removed publishable/client key: update the prompt_cli_login signature and any call sites to remove the publishable_client_key parameter and rely only on project ID per the new env-var guidance; also verify and update the stack_auth_cli_template.py template so it does not expect publishable_client_key (remove its parameter and any references), and ensure any docs/examples calling prompt_cli_login pass only the project ID (and adjust parameter names if needed) to keep the examples consistent with the new cloud-project setup instructions.
🤖 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/interface/page-component-versions.ts`:
- Line 115: The guidance for the custom signOut page conflicts with the later
signOut prompt contract: instead of mandating an immediate redirect after
calling stackApp.signOut(), update the guidance for signOut (the line
referencing `stackApp.signOut()` and `stackApp.redirectToAfterSignOut({ replace:
true })`) to require that the page call `await stackApp.signOut()` and then
render a stable signed-out confirmation state (matching the dedicated `signOut`
prompt contract); only call `await stackApp.redirectToAfterSignOut({ replace:
true })` from the confirmation flow when you want to navigate away (or clarify
both places to accept immediate redirect). Ensure both the signOut guidance and
the signOut prompt text refer to the same behavior so they are consistent.
---
Outside diff comments:
In `@packages/stack-shared/src/ai/prompts.ts`:
- Around line 166-172: Update the Supabase setup example to remove the
now-incorrect NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY and align it with the new
env-var guidance by showing only the client-facing NEXT_PUBLIC_STACK_PROJECT_ID
and the server secret STACK_SECRET_SERVER_KEY; specifically, edit the example
block that currently lists NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY so it
instead shows NEXT_PUBLIC_STACK_PROJECT_ID=<your-stack-project-id> and
STACK_SECRET_SERVER_KEY=<your-secret-server-key>, ensuring the docs consistently
reference NEXT_PUBLIC_STACK_PROJECT_ID (client) and STACK_SECRET_SERVER_KEY
(server).
- Line 299: The CLI example uses a now-removed publishable/client key: update
the prompt_cli_login signature and any call sites to remove the
publishable_client_key parameter and rely only on project ID per the new env-var
guidance; also verify and update the stack_auth_cli_template.py template so it
does not expect publishable_client_key (remove its parameter and any
references), and ensure any docs/examples calling prompt_cli_login pass only the
project ID (and adjust parameter names if needed) to keep the examples
consistent with the new cloud-project setup instructions.
🪄 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: 6d678136-49b8-490c-ad85-cb90c724051d
📒 Files selected for processing (4)
docs-mintlify/guides/getting-started/setup.mdxdocs-mintlify/snippets/home-prompt-island.jsxpackages/stack-shared/src/ai/prompts.tspackages/stack-shared/src/interface/page-component-versions.ts
| |---|---| | ||
| | \`signIn\`, \`signUp\` | Render the forms described in this prompt (or its sign-in / sign-up counterpart). | | ||
| | \`oauthCallback\` | On mount, call \`await stackApp.callOAuthCallback()\`. The SDK exchanges the \`code\`/\`state\` query params for tokens and then redirects to \`afterSignIn\`. | | ||
| | \`signOut\` | On mount, call \`await stackApp.signOut()\` then \`await stackApp.redirectToAfterSignOut({ replace: true })\`. | |
There was a problem hiding this comment.
Sign-out guidance now conflicts with the existing signOut prompt contract.
Line 115 says the custom signOut page must redirect immediately after stackApp.signOut(), but the dedicated signOut prompt later in this file still requires a stable signed-out confirmation state. Please align these two contracts so generated guidance is consistent.
🤖 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 115,
The guidance for the custom signOut page conflicts with the later signOut prompt
contract: instead of mandating an immediate redirect after calling
stackApp.signOut(), update the guidance for signOut (the line referencing
`stackApp.signOut()` and `stackApp.redirectToAfterSignOut({ replace: true })`)
to require that the page call `await stackApp.signOut()` and then render a
stable signed-out confirmation state (matching the dedicated `signOut` prompt
contract); only call `await stackApp.redirectToAfterSignOut({ replace: true })`
from the confirmation flow when you want to navigate away (or clarify both
places to accept immediate redirect). Ensure both the signOut guidance and the
signOut prompt text refer to the same behavior so they are consistent.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
| 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. |
There was a problem hiding this comment.
Documentation incorrectly claims there is "no separate publishable / client key" while the codebase contains a PUBLISHABLE_CLIENT_KEY_REQUIRED_FOR_PROJECT error and examples showing actual use of publishable client keys.
Summary
STACK_PROJECT_ID(plusSTACK_SECRET_SERVER_KEYserver-side) are the complete env-var set — there is no separate publishable / client key, and any third slot in.env.localis wrong.NEXT_PUBLIC_…,VITE_…) and explicitly note the server key must never be prefixed/exposed.urls.default, so OAuth / magic-link / sign-out / verification flows will visibly redirect through<projectId>.built-with-stack-auth.comunless each is customized.signIn,signUp,oauthCallback,signOut,magicLinkCallback,forgotPassword, …) and the SDK call each custom page must invoke.REDIRECT_URL_NOT_WHITELISTED.docs-mintlify/guides/getting-started/setup.mdxandhome-prompt-island.jsxfrom the updated prompt source.Test plan
pnpm lintpnpm typecheckSummary by CodeRabbit