mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-04 21:04:37 +08:00
fix(init-prompt): require StackProvider for all frameworks (#1374)
## Summary - The init prompt marked the `StackProvider` step as *React only* and placed it after the `StackHandler` step. Following it on a Next.js project produced a layout with no provider, so `StackHandler` crashed at runtime with `useStackApp must be used within a StackProvider`. - Make the provider step unconditional and move it ahead of the handler step so the dependency order matches the instruction order. Also quote the exact error message so the model won't skip it. ## Test plan - [ ] Run `npx @stackframe/stack-cli init` (or the web flow) against a fresh Next.js app and confirm `/handler/[...stack]` renders without the `useStackApp` error. - [ ] Re-run against a Vite/React app to confirm the reordered instructions still produce a working setup. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added explicit global MCP config file path guidance for several coding agents. * Documented required provider configuration across supported frameworks. * Clarified where to place provider wrappers in root app layouts (including Next.js app/layout). * Reordered setup steps to surface the required "Wrap your app in a Stack provider" step and updated step numbering. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
parent
4a2595d9f7
commit
d1751a7634
@ -8,7 +8,11 @@ These instructions describe how to set up Stack Auth.
|
||||
${web ? `
|
||||
First of all, if you have access to a terminal, it is better to use the \`npx @stackframe/stack-cli init\`` : ""}
|
||||
|
||||
Install mcp server from https://mcp.stack-auth.com if not already installed
|
||||
Install mcp server from https://mcp.stack-auth.com if not already installed. Global MCP config file paths for popular coding agents:
|
||||
- Claude Code: \`~/.claude.json\`
|
||||
- Codex CLI: \`~/.codex/config.toml\`
|
||||
- Cursor: \`~/.cursor/mcp.json\`
|
||||
- opencode: \`~/.config/opencode/opencode.json\`
|
||||
|
||||
For reference, questions, or information on Stack Auth, you can query the docs on https://docs.stack-auth.com via curl or any tools that you have
|
||||
|
||||
@ -65,50 +69,12 @@ export const stackServerApp = new StackServerApp({
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
### 3) Create the Stack handler (if available in framework)
|
||||
### 3) Wrap your app in a Stack provider
|
||||
|
||||
This sets up pages for sign in, sign up, password reset, etc.
|
||||
Required for all React based frameworks (including Next.js). \`StackHandler\`, \`useUser\`, and \`useStackApp\` all depend on it — without it you will get "useStackApp must be used within a StackProvider" at runtime. In Next.js, add it to the root \`app/layout.tsx\` around \`{children}\`. In React/Vite, wrap your root component.
|
||||
|
||||
\`\`\`tsx
|
||||
import { StackHandler } from "@stackframe/stack"; // Next.js
|
||||
// import { StackHandler } from "@stackframe/react"; // React
|
||||
|
||||
export default function Handler() {
|
||||
return <StackHandler fullPage />;
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### 4) Create a Suspense boundary
|
||||
|
||||
Suspense is necessary for many stack auth hooks such as useUser to function. Add a loading component with a custom loading indicator for the current project. Don't add if one already exists
|
||||
|
||||
For example:
|
||||
\`\`\`tsx
|
||||
//src/loading.tsx
|
||||
|
||||
export default function Loading() {
|
||||
return <p>Loading...</p>
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### 5) Link environment variables
|
||||
|
||||
This is only necessary if not using local emulator. Ensure these are ignored by git.
|
||||
|
||||
Rename the env var keys in .env to match the framework's convention for client-exposed variables. For example, Vite requires VITE_ prefix, Next.js uses NEXT_PUBLIC_, etc. The values should stay the same — only rename the keys.
|
||||
|
||||
The required variables are:
|
||||
- Project ID (e.g. NEXT_PUBLIC_STACK_PROJECT_ID, VITE_STACK_PROJECT_ID, etc.)
|
||||
- Secret server key: STACK_SECRET_SERVER_KEY (only for frameworks with server-side support, no prefix needed)
|
||||
|
||||
The publishable client key (e.g. NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, VITE_STACK_PUBLISHABLE_CLIENT_KEY, etc.) is only required if your project has publishable client keys enabled as a requirement.
|
||||
|
||||
### 6) React only: Wrap the entire page in a Stack provider
|
||||
|
||||
This is used for the useUser and useStackApp hooks.
|
||||
|
||||
\`\`\`tsx
|
||||
import { StackProvider, StackTheme } from "@stackframe/stack";
|
||||
import { StackProvider, StackTheme } from "@stackframe/stack"; // or "@stackframe/react"
|
||||
import { stackClientApp } from "../stack/client"; // adjust relative path
|
||||
\`\`\`
|
||||
|
||||
@ -123,4 +89,43 @@ return (
|
||||
</body>
|
||||
);
|
||||
\`\`\`
|
||||
|
||||
### 4) Create the Stack handler (if available in framework)
|
||||
|
||||
This sets up pages for sign in, sign up, password reset, etc.
|
||||
|
||||
\`\`\`tsx
|
||||
import { StackHandler } from "@stackframe/stack"; // Next.js
|
||||
// import { StackHandler } from "@stackframe/react"; // React
|
||||
|
||||
export default function Handler() {
|
||||
return <StackHandler fullPage />;
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### 5) Create a Suspense boundary
|
||||
|
||||
Suspense is necessary for many stack auth hooks such as useUser to function. Add a loading component with a custom loading indicator for the current project. Don't add if one already exists
|
||||
|
||||
For example:
|
||||
\`\`\`tsx
|
||||
//src/loading.tsx
|
||||
|
||||
export default function Loading() {
|
||||
return <p>Loading...</p>
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### 6) Link environment variables
|
||||
|
||||
This is only necessary if not using local emulator. Ensure these are ignored by git.
|
||||
|
||||
Rename the env var keys in .env to match the framework's convention for client-exposed variables. For example, Vite requires VITE_ prefix, Next.js uses NEXT_PUBLIC_, etc. The values should stay the same — only rename the keys.
|
||||
|
||||
The required variables are:
|
||||
- Project ID (e.g. NEXT_PUBLIC_STACK_PROJECT_ID, VITE_STACK_PROJECT_ID, etc.)
|
||||
- Secret server key: STACK_SECRET_SERVER_KEY (only for frameworks with server-side support, no prefix needed)
|
||||
|
||||
The publishable client key (e.g. NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, VITE_STACK_PUBLISHABLE_CLIENT_KEY, etc.) is only required if your project has publishable client keys enabled as a requirement.
|
||||
|
||||
`;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user