Skip to content

Commit 53ff6f1

Browse files
N2D4N2D4
committed
Update setup instructions
1 parent cd52b36 commit 53ff6f1

2 files changed

Lines changed: 212 additions & 22 deletions

File tree

‎docs/content/setup-instructions.md‎

Lines changed: 106 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,27 @@ Follow this workflow without asking for extra clarification unless a step fails.
1010

1111
---
1212

13+
### 0) Framework Detection (REQUIRED FIRST STEP)
14+
Before proceeding, you MUST identify the project framework:
15+
- **Check for Next.js**: Look for `next.config.js`, `next.config.mjs`, or `package.json` with Next.js dependencies
16+
- **Check for React**: Look for `package.json` with React dependencies but NO Next.js dependencies
17+
- **If neither is detected**: STOP and alert the user that Stack Auth only supports Next.js and React projects
18+
- **If framework is unclear**: STOP and ask the user to clarify their project type
19+
20+
**IMPORTANT**: Only proceed with the installation if you can clearly identify the project as either Next.js or React.
21+
1322
### 1) Run the Stack Auth initializer
1423
- Use the `stack-auth` MCP server.
1524
- Call the tool or run the command:
16-
```bash
17-
STACK_DISABLE_INTERACTIVE=1 npx @stackframe/init-stack@latest
18-
```
19-
- Accept defaults for Next.js (App Router).
25+
- **For Next.js projects**:
26+
```bash
27+
npx @stackframe/init-stack@latest --on-question error
28+
```
29+
- **For React projects**:
30+
```bash
31+
npx @stackframe/init-stack@latest --react --on-question error
32+
```
33+
- Accept defaults for Next.js (App Router) or React.
2034
- Add all generated files to the repo.
2135

2236
### 2) Scaffold the auth setup
@@ -28,6 +42,8 @@ Confirm these files exist (created by the initializer):
2842
Ensure they are added to the repo.
2943

3044
### 3) Environment Variables (HUMAN ACTION REQUIRED)
45+
46+
#### For Next.js Projects:
3147
Required vars (from Stack dashboard):
3248
- `NEXT_PUBLIC_STACK_PROJECT_ID`
3349
- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
@@ -37,19 +53,63 @@ Check `.env.local`:
3753
- If the file is unreadable (ignored or access denied), DO NOT assume it's configured.
3854
- If any required var is missing or empty, prompt the user and PAUSE.
3955
40-
Show this exact message (verbatim), then wait for reply:
56+
#### For React Projects:
57+
Create a new file called `stack/client.ts` and add the following code:
58+
59+
react-router
60+
```typescript
61+
import { StackClientApp } from "@stackframe/react";
62+
// import { useNavigate } from "react-router-dom";
63+
64+
export const stackClientApp = new StackClientApp({
65+
// You should store these in environment variables
66+
projectId: "YOUR_PROJECT_ID_HERE",
67+
publishableClientKey: "YOUR_PUBLISHABLE_CLIENT_KEY_HERE",
68+
tokenStore: "cookie",
69+
// redirectMethod: {
70+
// useNavigate,
71+
// }
72+
});
73+
```
74+
75+
**⚠️ MANDATORY STOP POINT ⚠️**
76+
**DO NOT CONTINUE TO STEP 4 UNTIL USER ADDS THEIR KEYS**
4177
78+
Show this exact message (verbatim), then **STOP AND WAIT**:
79+
80+
**For Next.js Projects:**
4281
```
4382
=== ACTION REQUIRED ===
4483
TODO in your web browser:
4584
1) Open: https://app.stack-auth.com (→ your project dashboard)
4685
2) Create a new project
47-
3) Copy these keys:
86+
3) Choose your framework: Next.js
87+
4) Copy these keys:
4888
- NEXT_PUBLIC_STACK_PROJECT_ID=...
4989
- NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=...
5090
- STACK_SECRET_SERVER_KEY=...
51-
4) Paste them into your local `.env.local` (do not commit this file).
52-
5) Save the file.
91+
5) Paste them into your local `.env.local` (do not commit this file).
92+
6) Save the file.
93+
94+
Reply here when done:
95+
- Type **y** to continue
96+
- Type **n** to cancel
97+
```
98+
99+
**For React Projects:**
100+
```
101+
=== ACTION REQUIRED ===
102+
TODO in your web browser:
103+
1) Open: https://app.stack-auth.com (→ your project dashboard)
104+
2) Create a new project
105+
3) Choose your framework: React
106+
4) Copy these keys:
107+
- Project ID
108+
- Publishable Client Key
109+
5) Update the `stack/client.ts` file with your keys:
110+
- Replace "YOUR_PROJECT_ID_HERE" with your Project ID
111+
- Replace "YOUR_PUBLISHABLE_CLIENT_KEY_HERE" with your Publishable Client Key
112+
6) Save the file.
53113
54114
Reply here when done:
55115
- Type **y** to continue
@@ -59,13 +119,48 @@ Reply here when done:
59119
If user replies `n`: Stop and summarize what remains.
60120
61121
If user replies `y`:
62-
- If dev server is running, stop it.
63-
- Start it again so Next.js reloads env vars.
64-
- Proceed to Verification.
122+
- Proceed
65123
66124
### 4) Wrap the App
125+
126+
#### For Next.js Projects:
67127
Ensure the StackProvider from `src/stack.tsx` is wired into `src/app/layout.tsx`.
68128
129+
#### For React Projects:
130+
Update your App.tsx file (or equivalent if the user changed the naming) to wrap the entire app with a StackProvider and StackTheme and add a StackHandler component to handle the authentication flow.
131+
132+
```typescript
133+
import { StackHandler, StackProvider, StackTheme } from "@stackframe/react";
134+
import { Suspense } from "react";
135+
import { BrowserRouter, Route, Routes, useLocation } from "react-router-dom";
136+
import { stackClientApp } from "./stack/client";
137+
138+
function HandlerRoutes() {
139+
const location = useLocation();
140+
141+
return (
142+
<StackHandler app={stackClientApp} location={location.pathname} fullPage />
143+
);
144+
}
145+
146+
export default function App() {
147+
return (
148+
<StackProvider app={stackClientApp}>
149+
<StackTheme>
150+
<BrowserRouter>
151+
<Suspense fallback={<div>Loading...</div>}>
152+
<Routes>
153+
<Route path="*" element={<HandlerRoutes />} />
154+
{/* Your other routes here */}
155+
</Routes>
156+
</Suspense>
157+
</BrowserRouter>
158+
</StackTheme>
159+
</StackProvider>
160+
);
161+
}
162+
```
163+
69164
Do not log or print secret values.
70165
71166
### 5) Verification (must pass before committing)

‎docs/src/app/api/internal/[transport]/setup-instructions.md‎

Lines changed: 106 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,27 @@ Follow this workflow without asking for extra clarification unless a step fails.
1010

1111
---
1212

13+
### 0) Framework Detection (REQUIRED FIRST STEP)
14+
Before proceeding, you MUST identify the project framework:
15+
- **Check for Next.js**: Look for `next.config.js`, `next.config.mjs`, or `package.json` with Next.js dependencies
16+
- **Check for React**: Look for `package.json` with React dependencies but NO Next.js dependencies
17+
- **If neither is detected**: STOP and alert the user that Stack Auth only supports Next.js and React projects
18+
- **If framework is unclear**: STOP and ask the user to clarify their project type
19+
20+
**IMPORTANT**: Only proceed with the installation if you can clearly identify the project as either Next.js or React.
21+
1322
### 1) Run the Stack Auth initializer
1423
- Use the `stack-auth` MCP server.
1524
- Call the tool or run the command:
16-
```bash
17-
STACK_DISABLE_INTERACTIVE=1 npx @stackframe/init-stack@latest
18-
```
19-
- Accept defaults for Next.js (App Router).
25+
- **For Next.js projects**:
26+
```bash
27+
npx @stackframe/init-stack@latest --on-question error
28+
```
29+
- **For React projects**:
30+
```bash
31+
npx @stackframe/init-stack@latest --react --on-question error
32+
```
33+
- Accept defaults for Next.js (App Router) or React.
2034
- Add all generated files to the repo.
2135

2236
### 2) Scaffold the auth setup
@@ -28,6 +42,8 @@ Confirm these files exist (created by the initializer):
2842
Ensure they are added to the repo.
2943

3044
### 3) Environment Variables (HUMAN ACTION REQUIRED)
45+
46+
#### For Next.js Projects:
3147
Required vars (from Stack dashboard):
3248
- `NEXT_PUBLIC_STACK_PROJECT_ID`
3349
- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
@@ -37,19 +53,63 @@ Check `.env.local`:
3753
- If the file is unreadable (ignored or access denied), DO NOT assume it's configured.
3854
- If any required var is missing or empty, prompt the user and PAUSE.
3955
40-
Show this exact message (verbatim), then wait for reply:
56+
#### For React Projects:
57+
Create a new file called `stack/client.ts` and add the following code:
58+
59+
react-router
60+
```typescript
61+
import { StackClientApp } from "@stackframe/react";
62+
// import { useNavigate } from "react-router-dom";
63+
64+
export const stackClientApp = new StackClientApp({
65+
// You should store these in environment variables
66+
projectId: "YOUR_PROJECT_ID_HERE",
67+
publishableClientKey: "YOUR_PUBLISHABLE_CLIENT_KEY_HERE",
68+
tokenStore: "cookie",
69+
// redirectMethod: {
70+
// useNavigate,
71+
// }
72+
});
73+
```
74+
75+
**⚠️ MANDATORY STOP POINT ⚠️**
76+
**DO NOT CONTINUE TO STEP 4 UNTIL USER ADDS THEIR KEYS**
4177
78+
Show this exact message (verbatim), then **STOP AND WAIT**:
79+
80+
**For Next.js Projects:**
4281
```
4382
=== ACTION REQUIRED ===
4483
TODO in your web browser:
4584
1) Open: https://app.stack-auth.com (→ your project dashboard)
4685
2) Create a new project
47-
3) Copy these keys:
86+
3) Choose your framework: Next.js
87+
4) Copy these keys:
4888
- NEXT_PUBLIC_STACK_PROJECT_ID=...
4989
- NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=...
5090
- STACK_SECRET_SERVER_KEY=...
51-
4) Paste them into your local `.env.local` (do not commit this file).
52-
5) Save the file.
91+
5) Paste them into your local `.env.local` (do not commit this file).
92+
6) Save the file.
93+
94+
Reply here when done:
95+
- Type **y** to continue
96+
- Type **n** to cancel
97+
```
98+
99+
**For React Projects:**
100+
```
101+
=== ACTION REQUIRED ===
102+
TODO in your web browser:
103+
1) Open: https://app.stack-auth.com (→ your project dashboard)
104+
2) Create a new project
105+
3) Choose your framework: React
106+
4) Copy these keys:
107+
- Project ID
108+
- Publishable Client Key
109+
5) Update the `stack/client.ts` file with your keys:
110+
- Replace "YOUR_PROJECT_ID_HERE" with your Project ID
111+
- Replace "YOUR_PUBLISHABLE_CLIENT_KEY_HERE" with your Publishable Client Key
112+
6) Save the file.
53113
54114
Reply here when done:
55115
- Type **y** to continue
@@ -59,13 +119,48 @@ Reply here when done:
59119
If user replies `n`: Stop and summarize what remains.
60120
61121
If user replies `y`:
62-
- If dev server is running, stop it.
63-
- Start it again so Next.js reloads env vars.
64-
- Proceed to Verification.
122+
- Proceed
65123
66124
### 4) Wrap the App
125+
126+
#### For Next.js Projects:
67127
Ensure the StackProvider from `src/stack.tsx` is wired into `src/app/layout.tsx`.
68128
129+
#### For React Projects:
130+
Update your App.tsx file (or equivalent if the user changed the naming) to wrap the entire app with a StackProvider and StackTheme and add a StackHandler component to handle the authentication flow.
131+
132+
```typescript
133+
import { StackHandler, StackProvider, StackTheme } from "@stackframe/react";
134+
import { Suspense } from "react";
135+
import { BrowserRouter, Route, Routes, useLocation } from "react-router-dom";
136+
import { stackClientApp } from "./stack/client";
137+
138+
function HandlerRoutes() {
139+
const location = useLocation();
140+
141+
return (
142+
<StackHandler app={stackClientApp} location={location.pathname} fullPage />
143+
);
144+
}
145+
146+
export default function App() {
147+
return (
148+
<StackProvider app={stackClientApp}>
149+
<StackTheme>
150+
<BrowserRouter>
151+
<Suspense fallback={<div>Loading...</div>}>
152+
<Routes>
153+
<Route path="*" element={<HandlerRoutes />} />
154+
{/* Your other routes here */}
155+
</Routes>
156+
</Suspense>
157+
</BrowserRouter>
158+
</StackTheme>
159+
</StackProvider>
160+
);
161+
}
162+
```
163+
69164
Do not log or print secret values.
70165
71166
### 5) Verification (must pass before committing)

0 commit comments

Comments
 (0)