Convex-Gate: Better Auth Adapter for Convex

Common errors

• Error: Auth config provider must be passed via `convex({ authConfig })`

  cause The Convex plugin for Better Auth was not provided with the `authConfig` object.
  fix Ensure your `createAuthOptions` function correctly includes `convex({ authConfig }) as any,` within the plugins array.

• TypeError: Cannot read properties of undefined (reading 'betterAuth')

  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.
  fix Verify that `convex/convex.config.ts` includes `app.use(betterAuth);` and that `convex/convex.config.ts` is correctly imported and run.

• HTTP 401 Unauthorized during client-side authentication attempts.

  cause CORS settings might be misconfigured on the Convex HTTP routes, or the `trustedOrigins` in `createAuthOptions` does not match the client's URL.
  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`).

Warnings

• breaking This package is currently in alpha. APIs are subject to change between releases, and it is not yet recommended for production use.
  Fix: Monitor changelogs closely for updates and breaking changes. Be prepared for potential API shifts in minor or patch releases.
• gotcha Social OAuth logins were broken by the Better Auth Proxy in v0.1.1. This was fixed in v0.1.2.
  Fix: Upgrade to `convex-gate@0.1.2` or higher to resolve issues with social OAuth logins.
• gotcha Security hardening was introduced in v0.1.3, addressing CORS, CSRF, cache TTL, and debug lockdown settings.
  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.
• breaking The `authComponent` adapter requires `components.betterAuth` from the Convex generated API. Ensure the Convex component is correctly registered and named `betterAuth`.
  Fix: Verify that `convex/convex.config.ts` correctly registers `app.use(betterAuth)` and that `convex/_generated/api.ts` contains `components.betterAuth`.

Install

• npm install convex-gate npm
• yarn add convex-gate yarn
• pnpm add convex-gate pnpm

Imports

• betterAuth
  wrong:

  import { betterAuth } from 'convex-gate/convex.config';

  correct:

  import betterAuth from 'convex-gate/convex.config';

  This is a default import for registering the Convex component configuration.
• getAuthConfigProvider
  wrong:

  import getAuthConfigProvider from 'convex-gate/auth-config';

  correct:

  import { getAuthConfigProvider } from 'convex-gate/auth-config';

  A named import for obtaining the auth configuration provider function.
• createClient
  wrong:

  const createClient = require('convex-gate').createClient;

  correct:

  import { createClient } from 'convex-gate';

  Used for creating the Convex-Gate client instance, typically on the server-side. The package primarily uses ESM.
• ConvexBetterAuthProvider
  wrong:

  import ConvexBetterAuthProvider from 'convex-gate/react';

  correct:

  import { ConvexBetterAuthProvider } from 'convex-gate/react';

  A named import for the React context provider on the client-side.

Quickstart

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.

import { ConvexReactClient } from "convex/react";
import { ConvexBetterAuthProvider } from "convex-gate/react";
import { authClient } from "./lib/auth-client";
import { createAuthClient } from "better-auth/react";
import { convexClient, crossDomainClient } from "convex-gate/client/plugins";
import React from 'react';
import ReactDOM from 'react-dom/client';

// --- Client Auth Setup (src/lib/auth-client.ts) ---
export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_CONVEX_SITE_URL ?? '', // Use empty string if undefined for SSR compatibility
  plugins: [
    crossDomainClient(),
    convexClient(),
  ],
});

// --- Main App Component (src/App.tsx) ---
import { Authenticated, Unauthenticated } from "convex/react";

function App() {
  return (
    <>
      <h1>Convex-Gate Demo</h1>
      <Authenticated>
        <p>You are authenticated!</p>
        <button onClick={() => authClient.signOut()}>Sign Out</button>
      </Authenticated>
      <Unauthenticated>
        <p>Please sign in.</p>
        <form onSubmit={(e) => {
          e.preventDefault();
          const formData = new FormData(e.currentTarget);
          const email = formData.get('email')?.toString();
          const password = formData.get('password')?.toString();
          if (email && password) {
            authClient.signIn.email({ email, password });
          }
        }}>
          <input type="email" name="email" placeholder="Email" required />
          <input type="password" name="password" placeholder="Password" required />
          <button type="submit">Sign In</button>
        </form>
      </Unauthenticated>
    </>
  );
}

// --- Root Render (src/main.tsx) ---
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL ?? '');

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <ConvexBetterAuthProvider client={convex} authClient={authClient}>
      <App />
    </ConvexBetterAuthProvider>
  </React.StrictMode>
);