fix(init-prompt): require StackProvider for all frameworks (#1374)

BilalG1 · web-flow · commit d1751a7634ec · 2026-04-24T12:27:49.000-07:00
## 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.

&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## 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.
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/packages/stack-shared/src/helpers/init-prompt.ts b/packages/stack-shared/src/helpers/init-prompt.ts
@@ -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,7 +69,28 @@ export const stackServerApp = new StackServerApp({
 });
 \`\`\`
 
-### 3) Create the Stack handler (if available in framework)
+### 3) Wrap your app in a Stack provider
+
+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 { StackProvider, StackTheme } from "@stackframe/stack"; // or "@stackframe/react" 
+import { stackClientApp } from "../stack/client"; // adjust relative path
+\`\`\`
+
+Then wrap the body content:
+
+\`\`\`tsx
+return (
+  <body>
+    <StackProvider app={stackClientApp}>
+      <StackTheme>{children}</StackTheme>
+    </StackProvider>
+  </body>
+);
+\`\`\`
+
+### 4) Create the Stack handler (if available in framework)
 
 This sets up pages for sign in, sign up, password reset, etc.
 
@@ -78,7 +103,7 @@ export default function Handler() {
 }
 \`\`\`
 
-### 4) Create a Suspense boundary
+### 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
 
@@ -91,7 +116,7 @@ export default function Loading() {
 }
 \`\`\`
 
-### 5) Link environment variables
+### 6) Link environment variables
 
 This is only necessary if not using local emulator. Ensure these are ignored by git.
 
@@ -103,24 +128,4 @@ The required variables are:
 
 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 { stackClientApp } from "../stack/client"; // adjust relative path
-\`\`\`
-
-Then wrap the body content:
-
-\`\`\`tsx
-return (
-  <body>
-    <StackProvider app={stackClientApp}>
-      <StackTheme>{children}</StackTheme>
-    </StackProvider>
-  </body>
-);
-\`\`\`
 `;
