Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
betterAuth
✓ import betterAuth from 'convex-gate/convex.config';
✗ import { betterAuth } from 'convex-gate/convex.config';
This is a default import for registering the Convex component configuration.
getAuthConfigProvider
✓ import { getAuthConfigProvider } from 'convex-gate/auth-config';
✗ import getAuthConfigProvider from 'convex-gate/auth-config';
A named import for obtaining the auth configuration provider function.
createClient
✓ import { createClient } from 'convex-gate';
✗ const createClient = require('convex-gate').createClient;
Used for creating the Convex-Gate client instance, typically on the server-side. The package primarily uses ESM.
ConvexBetterAuthProvider
✓ import { ConvexBetterAuthProvider } from 'convex-gate/react';
✗ import ConvexBetterAuthProvider from 'convex-gate/react';
A named import for the React context provider on the client-side.
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>
);
Errors
Common errors & fixes
Error: Auth config provider must be passed via `convex({ authConfig })`
The Convex plugin for Better Auth was not provided with the `authConfig` object.
fixEnsure your `createAuthOptions` function correctly includes `convex({ authConfig }) as any,` within the plugins array. TypeError: Cannot read properties of undefined (reading 'betterAuth')
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.
fixVerify 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.
CORS settings might be misconfigured on the Convex HTTP routes, or the `trustedOrigins` in `createAuthOptions` does not match the client's URL.
fixCheck that `authComponent.registerRoutes(http, createAuth, { cors: true });` is present and that `trustedOrigins: [siteUrl]` includes all necessary client origins, especially in development (`http://localhost:XXXX`). Audit
Dependencies
better-authrequiredCore authentication library it adapts to Convex.
convexrequiredThe Convex backend framework it integrates with.
reactoptionalRequired for the client-side React bindings and provider.