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:
BilalG1 2026-04-24 12:27:49 -07:00 committed by GitHub
parent 4a2595d9f7
commit d1751a7634
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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.
`;