From 77777a5aed8dce24299ce145ed4c89661ab550c7 Mon Sep 17 00:00:00 2001
From: Konstantin Wohlwend <n2d4xc@gmail.com>
Date: Fri, 10 Oct 2025 04:28:09 -0700
Subject: [PATCH] Actual Convex README

---
 .../integrations/convex/component/README.md   | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 packages/template/src/integrations/convex/component/README.md

diff --git a/packages/template/src/integrations/convex/component/README.md b/packages/template/src/integrations/convex/component/README.md
new file mode 100644
index 000000000..c7fdcdbe3
--- /dev/null
+++ b/packages/template/src/integrations/convex/component/README.md
@@ -0,0 +1,59 @@
+# Stack Auth Convex Component
+
+This component is the official way to integrate Stack Auth with your Convex project.
+
+## Installation
+
+To get started, first install Stack Auth using the setup wizard:
+
+```bash
+npx @stackframe/init-stack@latest
+```
+
+## Get Started
+
+[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.
+
+Next, update or create a file in `convex/auth.config.ts`:
+
+```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:
+
+```ts
+convexClient.setAuth(stackServerApp.getConvexClientAuth());  // browser JS
+convexReactClient.setAuth(stackServerApp.getConvexClientAuth());  // React
+convexHttpClient.setAuth(stackServerApp.getAuthForConvexHttpClient({ tokenStore: requestObject }));  // HTTP, see Stack Auth docs for more information on tokenStore
+```
+
+Now, you'll be able to access Stack Auth's functionality from your frontend & backend:
+
+```ts
+// 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);
+  },
+});
+```
+
+For more information on how to use Stack Auth, see the [Stack Auth docs](https://docs.stack-auth.com).