{"id":16792,"library":"convex-gate","title":"Convex-Gate: Better Auth Adapter for Convex","description":"Convex-Gate is an alpha-stage package designed to integrate the Better Auth authentication system with Convex applications. It provides an isolated authentication data store within a Convex component, separating auth concerns from application data. Key features include a dedicated hot-path for rapid session resolution, server-side JWT caching with configurable TTL, client-side token expiry awareness, and support for static JWKS. It also offers React bindings via `ConvexBetterAuthProvider` and is compatible with all Better Auth plugins (2FA, SSO, organizations, passkeys). The current version is 0.1.3, and due to its alpha status, APIs are subject to change. Release cadence is currently irregular as it's under active development.","status":"active","version":"0.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/VexoaXYZ/convex-gate","tags":["javascript","convex","better-auth","auth","authentication","adapter","jwt","jwks","react"],"install":[{"cmd":"npm install convex-gate","lang":"bash","label":"npm"},{"cmd":"yarn add convex-gate","lang":"bash","label":"yarn"},{"cmd":"pnpm add convex-gate","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication library it adapts to Convex.","package":"better-auth","optional":false},{"reason":"The Convex backend framework it integrates with.","package":"convex","optional":false},{"reason":"Required for the client-side React bindings and provider.","package":"react","optional":true}],"imports":[{"note":"This is a default import for registering the Convex component configuration.","wrong":"import { betterAuth } from 'convex-gate/convex.config';","symbol":"betterAuth","correct":"import betterAuth from 'convex-gate/convex.config';"},{"note":"A named import for obtaining the auth configuration provider function.","wrong":"import getAuthConfigProvider from 'convex-gate/auth-config';","symbol":"getAuthConfigProvider","correct":"import { getAuthConfigProvider } from 'convex-gate/auth-config';"},{"note":"Used for creating the Convex-Gate client instance, typically on the server-side. The package primarily uses ESM.","wrong":"const createClient = require('convex-gate').createClient;","symbol":"createClient","correct":"import { createClient } from 'convex-gate';"},{"note":"A named import for the React context provider on the client-side.","wrong":"import ConvexBetterAuthProvider from 'convex-gate/react';","symbol":"ConvexBetterAuthProvider","correct":"import { ConvexBetterAuthProvider } from 'convex-gate/react';"}],"quickstart":{"code":"import { ConvexReactClient } from \"convex/react\";\nimport { ConvexBetterAuthProvider } from \"convex-gate/react\";\nimport { authClient } from \"./lib/auth-client\";\nimport { createAuthClient } from \"better-auth/react\";\nimport { convexClient, crossDomainClient } from \"convex-gate/client/plugins\";\nimport React from 'react';\nimport ReactDOM from 'react-dom/client';\n\n// --- Client Auth Setup (src/lib/auth-client.ts) ---\nexport const authClient = createAuthClient({\n  baseURL: import.meta.env.VITE_CONVEX_SITE_URL ?? '', // Use empty string if undefined for SSR compatibility\n  plugins: [\n    crossDomainClient(),\n    convexClient(),\n  ],\n});\n\n// --- Main App Component (src/App.tsx) ---\nimport { Authenticated, Unauthenticated } from \"convex/react\";\n\nfunction App() {\n  return (\n    <>\n      <h1>Convex-Gate Demo</h1>\n      <Authenticated>\n        <p>You are authenticated!</p>\n        <button onClick={() => authClient.signOut()}>Sign Out</button>\n      </Authenticated>\n      <Unauthenticated>\n        <p>Please sign in.</p>\n        <form onSubmit={(e) => {\n          e.preventDefault();\n          const formData = new FormData(e.currentTarget);\n          const email = formData.get('email')?.toString();\n          const password = formData.get('password')?.toString();\n          if (email && password) {\n            authClient.signIn.email({ email, password });\n          }\n        }}>\n          <input type=\"email\" name=\"email\" placeholder=\"Email\" required />\n          <input type=\"password\" name=\"password\" placeholder=\"Password\" required />\n          <button type=\"submit\">Sign In</button>\n        </form>\n      </Unauthenticated>\n    </>\n  );\n}\n\n// --- Root Render (src/main.tsx) ---\nconst convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL ?? '');\n\nReactDOM.createRoot(document.getElementById(\"root\")!).render(\n  <React.StrictMode>\n    <ConvexBetterAuthProvider client={convex} authClient={authClient}>\n      <App />\n    </ConvexBetterAuthProvider>\n  </React.StrictMode>\n);\n","lang":"typescript","description":"This code sets up the client-side authentication for a React application using Convex-Gate. It initializes the Better Auth client with Convex-Gate plugins, wraps the application with `ConvexBetterAuthProvider`, and demonstrates conditional rendering based on authentication status with sign-in and sign-out functionality."},"warnings":[{"fix":"Monitor changelogs closely for updates and breaking changes. Be prepared for potential API shifts in minor or patch releases.","message":"This package is currently in alpha. APIs are subject to change between releases, and it is not yet recommended for production use.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Upgrade to `convex-gate@0.1.2` or higher to resolve issues with social OAuth logins.","message":"Social OAuth logins were broken by the Better Auth Proxy in v0.1.1. This was fixed in v0.1.2.","severity":"gotcha","affected_versions":"0.1.1"},{"fix":"Update to `convex-gate@0.1.3` or newer to benefit from enhanced security measures. Review configuration options related to CORS, CSRF, cache TTL, and debug modes.","message":"Security hardening was introduced in v0.1.3, addressing CORS, CSRF, cache TTL, and debug lockdown settings.","severity":"gotcha","affected_versions":"<0.1.3"},{"fix":"Verify that `convex/convex.config.ts` correctly registers `app.use(betterAuth)` and that `convex/_generated/api.ts` contains `components.betterAuth`.","message":"The `authComponent` adapter requires `components.betterAuth` from the Convex generated API. Ensure the Convex component is correctly registered and named `betterAuth`.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your `createAuthOptions` function correctly includes `convex({ authConfig }) as any,` within the plugins array.","cause":"The Convex plugin for Better Auth was not provided with the `authConfig` object.","error":"Error: Auth config provider must be passed via `convex({ authConfig })`"},{"fix":"Verify that `convex/convex.config.ts` includes `app.use(betterAuth);` and that `convex/convex.config.ts` is correctly imported and run.","cause":"The `betterAuth` component was not properly defined or imported into the `_generated/api.ts` file, or the component registration in `convex.config.ts` is missing.","error":"TypeError: Cannot read properties of undefined (reading 'betterAuth')"},{"fix":"Check that `authComponent.registerRoutes(http, createAuth, { cors: true });` is present and that `trustedOrigins: [siteUrl]` includes all necessary client origins, especially in development (`http://localhost:XXXX`).","cause":"CORS settings might be misconfigured on the Convex HTTP routes, or the `trustedOrigins` in `createAuthOptions` does not match the client's URL.","error":"HTTP 401 Unauthorized during client-side authentication attempts."}],"ecosystem":"npm","meta_description":null}