Convex
Integrate Stack Auth with Convex
This guide shows how to integrate Stack Auth with Convex.
1) Create a Convex + Next.js app
First, initialize a new Convex + Next.js app:
npm create convex@latest # make sure to choose "Next.js" and "No auth" when asked — we will add auth laterThen, run npx convex dev to start the Convex backend, and npm run dev to start the development server.
2) Install Stack Auth
Next, install Stack Auth using the setup wizard:
cd my-app/ # replace with your app name
npx @stackframe/init-stack@latest3) Create a Stack Auth project
Create a new Stack Auth project. Get the project ID & API key environment variables from the dashboard.
- Set the
.env.localfile to the environment variables. - In Convex, go to the dashboard of your project's deployment, and also set the environment variables there.
4) Update code
Next, update or create a file in convex/auth.config.ts:
import { getConvexProvidersConfig } from "@stackframe/js"; // Vanilla JS
// or: import { getConvexProvidersConfig } from "@stackframe/react"; // React
// or: import { getConvexProvidersConfig } from "@stackframe/stack"; // Next.js
export default {
providers: getConvexProvidersConfig({
projectId: process.env.STACK_PROJECT_ID, // or: process.env.NEXT_PUBLIC_STACK_PROJECT_ID
}),
}Then, update your Convex client to use Stack Auth:
convexClient.setAuth(stackClientApp.getConvexClientAuth({})); // browser JS
convexReactClient.setAuth(stackClientApp.getConvexClientAuth({})); // React
convexHttpClient.setAuth(stackClientApp.getConvexHttpClientAuth({ tokenStore: requestObject })); // HTTP, see Stack Auth docs for more information on tokenStore5) Done!
Done! Now, you'll be able to access Stack Auth's functionality from your frontend & backend:
// MyPage.tsx
export function MyPage() {
// see https://docs.stack-auth.com for more information on how to use Stack Auth
const user = useUser();
return <div>Your email is {user.email}</div>;
}
// myFunctions.ts
export const myQuery = query({
handler: async (ctx, args) => {
// In queries & mutations, use the special `getPartialUser` function to get user info
const obj = await stackServerApp.getPartialUser({ from: "convex", ctx });
return JSON.stringify(obj);
},
});You can find the production-ready template with Stack-Auth, Convex & Shadcn pre-configured here on GitHub.