Skip to content

Commit 4387a2c

Browse files
N2D4N2D4
committed
Update Convex docs
1 parent 53ff6f1 commit 4387a2c

3 files changed

Lines changed: 61 additions & 82 deletions

File tree

‎docs/templates/others/convex.mdx‎

Lines changed: 52 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -7,95 +7,74 @@ This guide shows how to integrate Stack Auth with Convex.
77

88
### 1) Create a Convex + Next.js app
99

10+
First, initialize a new Convex + Next.js app:
11+
1012
```bash title="Terminal"
11-
npx create-next-app --example convex stack-convex
12-
cd stack-convex
13+
npm create convex@latest # make sure to choose "Next.js" and "No auth" when asked — we will add auth later
14+
```
15+
16+
Then, run `npx convex dev` to start the Convex backend, and `npm run dev` to start the development server.
17+
18+
### 2) Install Stack Auth
19+
20+
Next, install Stack Auth using the setup wizard:
21+
22+
```bash
23+
cd my-app/ # replace with your app name
1324
npx @stackframe/init-stack@latest
1425
```
1526

16-
Add your Stack environment variables to both `.env.local` and convex env:
17-
- `NEXT_PUBLIC_STACK_PROJECT_ID`
18-
- `NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`
19-
- `STACK_SECRET_SERVER_KEY`
27+
### 3) Create a Stack Auth project
28+
29+
[Create a new Stack Auth project](https://app.stack-auth.com). Get the project ID & API key environment variables from the dashboard.
2030

21-
### 2) Update `convex/auth.config.ts`
31+
- Set the `.env.local` file to the environment variables.
32+
- In Convex, go to the dashboard of your project's deployment, and also set the environment variables there.
2233

23-
Use the exported helper to configure Convex auth providers for Stack. If `NEXT_PUBLIC_STACK_PROJECT_ID` is set, the `projectId` option is optional.
34+
### 4) Update code
2435

25-
```typescript title="convex/auth.config.ts"
26-
import { getConvexProvidersConfig } from "@stackframe/stack";
36+
Next, update or create a file in `convex/auth.config.ts`:
37+
38+
```ts
39+
import { getConvexProvidersConfig } from "@stackframe/js"; // Vanilla JS
40+
// or: import { getConvexProvidersConfig } from "@stackframe/react"; // React
41+
// or: import { getConvexProvidersConfig } from "@stackframe/stack"; // Next.js
2742

2843
export default {
2944
providers: getConvexProvidersConfig({
30-
// Optional: projectId: PROJECT_ID,
45+
projectId: process.env.STACK_PROJECT_ID, // or: process.env.NEXT_PUBLIC_STACK_PROJECT_ID
3146
}),
32-
};
47+
}
3348
```
3449

35-
### 3) Create your Stack client
36-
37-
```typescript title="stack/client.ts"
38-
import { StackClientApp } from "@stackframe/stack";
50+
Then, update your Convex client to use Stack Auth:
3951

40-
export const stackClientApp = new StackClientApp({
41-
tokenStore: "nextjs-cookie",
42-
});
52+
```ts
53+
convexClient.setAuth(stackServerApp.getConvexClientAuth()); // browser JS
54+
convexReactClient.setAuth(stackServerApp.getConvexClientAuth()); // React
55+
convexHttpClient.setAuth(stackServerApp.getAuthForConvexHttpClient({ tokenStore: requestObject })); // HTTP, see Stack Auth docs for more information on tokenStore
4356
```
4457

45-
### 4) Use with Convex clients
46-
47-
<Tabs defaultValue="react">
48-
<TabsList>
49-
<TabsTrigger value="react">Convex React client</TabsTrigger>
50-
<TabsTrigger value="http">Convex HTTP client</TabsTrigger>
51-
</TabsList>
52-
<TabsContent value="react">
53-
<Steps>
54-
<Step>
55-
### Set auth for Convex React client
56-
</Step>
57-
```tsx title="convex-react.ts"
58-
import { ConvexReactClient } from "convex/react";
59-
import { stackClientApp } from "../stack/client";
60-
61-
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!, { expectAuth: true });
62-
convex.setAuth(
63-
stackClientApp.getConvexClientAuth({ tokenStore: "nextjs-cookie" })
64-
);
65-
```
66-
</Steps>
67-
</TabsContent>
68-
<TabsContent value="http">
69-
<Steps>
70-
<Step>
71-
### Set auth for Convex HTTP client
72-
</Step>
73-
```ts title="convex-http.ts"
74-
import { ConvexHttpClient } from "convex/browser";
75-
import { stackClientApp } from "../stack/client";
76-
77-
const token = await stackClientApp.getConvexHttpClientAuth({ tokenStore: "nextjs-cookie" });
78-
const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
79-
convex.setAuth(token);
80-
```
81-
</Steps>
82-
</TabsContent>
83-
</Tabs>
84-
85-
### 5) Use in Convex functions (server)
86-
87-
In Convex queries/mutations/actions, map Convex identity to a Stack partial user with `ctx`:
88-
89-
```ts title="convex/myFunctions.ts"
90-
import { v } from "convex/values";
91-
import { query } from "./_generated/server";
92-
import { stackClientApp } from "../stack/client";
93-
94-
export const whoAmI = query({
95-
args: {},
96-
handler: async (ctx) => {
97-
const user = await stackClientApp.getPartialUser({ from: "convex", ctx });
98-
return user; // null when not authenticated
58+
### 5) Done!
59+
60+
Done! Now, you'll be able to access Stack Auth's functionality from your frontend & backend:
61+
62+
```ts
63+
// MyPage.tsx
64+
export function MyPage() {
65+
// see https://docs.stack-auth.com for more information on how to use Stack Auth
66+
const user = useUser();
67+
return <div>Your email is {user.email}</div>;
68+
}
69+
70+
// myFunctions.ts
71+
export const myQuery = query({
72+
handler: async (ctx, args) => {
73+
// In queries & mutations, use the special `getPartialUser` function to get user info
74+
const obj = await stackServerApp.getPartialUser({ from: "convex", ctx });
75+
return JSON.stringify(obj);
9976
},
10077
});
10178
```
79+
80+
For more information on how to use Stack Auth, see the [Stack Auth docs](https://docs.stack-auth.com).

‎packages/init-stack/src/index.ts‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -532,21 +532,21 @@ const Steps = {
532532
return { error: `The project at ${projectPath} is using an unsupported version of Next.js (found ${nextVersionInPackageJson}).\n\nOnly Next.js 14 & 15 projects are currently supported. See Next's upgrade guide: https://nextjs.org/docs/app/building-your-application/upgrading/version-14` };
533533
}
534534

535+
const hasSrcAppFolder = fs.existsSync(path.join(projectPath, "src/app"));
536+
const srcPath = path.join(projectPath, hasSrcAppFolder ? "src" : "");
537+
const appPath = path.join(srcPath, "app");
538+
if (!fs.existsSync(appPath)) {
539+
return { error: `The app path ${appPath} does not exist. Only the Next.js App router is supported — are you maybe on the Pages router instead?` };
540+
}
541+
535542
const nextConfigPathWithoutExtension = path.join(projectPath, "next.config");
536543
const nextConfigFileExtension = await findJsExtension(
537544
nextConfigPathWithoutExtension
538545
);
539546
const nextConfigPath =
540547
nextConfigPathWithoutExtension + "." + (nextConfigFileExtension ?? "js");
541548
if (!fs.existsSync(nextConfigPath)) {
542-
return { error: `Expected file at ${nextConfigPath}. Only Next.js projects are currently supported.` };
543-
}
544-
545-
const hasSrcAppFolder = fs.existsSync(path.join(projectPath, "src/app"));
546-
const srcPath = path.join(projectPath, hasSrcAppFolder ? "src" : "");
547-
const appPath = path.join(srcPath, "app");
548-
if (!fs.existsSync(appPath)) {
549-
return { error: `The app path ${appPath} does not exist. Only the Next.js app router is supported.` };
549+
return { error: `Expected file at ${nextConfigPath} for Next.js projects.` };
550550
}
551551

552552
const dryUpdateNextLayoutFileResult = await Steps.dryUpdateNextLayoutFile({ appPath, defaultExtension: "jsx" });

‎packages/template/src/integrations/convex/component/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ npx @stackframe/init-stack@latest
1212

1313
## Get Started
1414

15-
[Create a new Stack Auth project](https://app.stack-auth.com) and set the environment variables in Convex to the project ID & API key environment variables from the Stack Auth dashboard.
15+
[Create a new Stack Auth project](https://app.stack-auth.com) and set the environment variables in Convex to the project ID & API key environment variables from the Stack Auth dashboard. Also, add the same values to the `.env.local` file.
1616

1717
Next, update or create a file in `convex/auth.config.ts`:
1818

0 commit comments

Comments
 (0)