Convex-Zen Authentication Component

Common errors

• Module not found: Can't resolve 'convex-zen/next'

  cause This error occurs when a framework-specific component (like a provider) is imported from a subpath that doesn't exist, is misspelled, or when the bundler fails to resolve package `exports` conditions.
  fix Double-check the import path for the framework-specific component (e.g., `convex-zen/next`, `convex-zen/tanstack-start`). Ensure your project's build setup correctly handles package `exports` for subpath imports.

• TypeError: (0 , _convex_zen_next__WEBPACK_IMPORTED_MODULE_0__.ConvexProviderWithAuth) is not a function

  cause Often seen in bundled output, this indicates a mismatch in how modules are exported and imported, typically when a CommonJS-style `require` or incorrect named import tries to consume an ESM named export.
  fix Verify that your `tsconfig.json` has `"module": "ESNext"` (or a modern equivalent) and that your bundler is configured for full ESM compatibility. Confirm that `ConvexProviderWithAuth` is indeed a named export and not a default export.

• Convex client not initialized. Make sure you have wrapped your app in a <ConvexProvider>

  cause While a core Convex error, it frequently surfaces when `ConvexZenProvider` (which internally provides the Convex client) is not correctly placed at the root of your application, or when the `ConvexReactClient` instance passed to it is misconfigured.
  fix Ensure your main application component is wrapped by `ConvexProviderWithAuth` (or its framework-specific equivalent from `convex-zen`), and that a properly initialized `ConvexReactClient` instance is passed as the `client` prop.

Warnings

• breaking Convex-Zen has strict peer dependency requirements for the `convex` package. Using an incompatible `convex` version can lead to runtime errors, breaking changes, or unexpected behavior in authentication flows.
  Fix: Always align your `convex` dependency with the version range specified in `convex-zen`'s `peerDependencies`. For `convex-zen@1.13.5`, `convex@^1.35.1` is currently required.
• gotcha Framework-specific components and providers (e.g., `ConvexProviderWithAuth` for Next.js or Tanstack Start) are exposed through specific subpath exports. Importing them directly from the root `convex-zen` package will result in undefined symbols or module resolution failures.
  Fix: Ensure you use the correct subpath import for your framework, such as `import { ConvexProviderWithAuth } from 'convex-zen/next';` or `convex-zen/tanstack-start`.
• gotcha Proper setup requires defining `convex/zen.config.ts` and configuring `convex/auth.config.ts` to bridge with Convex-Zen. Furthermore, running `npx convex-zen generate` is crucial to process these configurations and generate necessary Convex functions and types. Skipping or misconfiguring these steps will lead to non-functional authentication.
  Fix: Meticulously follow the setup instructions for `zen.config.ts` and `auth.config.ts`. Always run `npx convex-zen generate` after any changes to these configuration files or your Convex schema.
• gotcha Convex-Zen is built primarily for modern JavaScript module environments (ESM). While bundlers generally handle this, direct usage or specific configurations in CommonJS-only projects might encounter module resolution issues.
  Fix: Configure your project to use ESM where possible, or ensure your build tools (e.g., Webpack, Rollup) are set up to correctly transpile and resolve ESM imports. The fix in v1.13.1 for 'explicit ESM import extensions' highlights this module compatibility.

Install

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

Imports

• defineConvexZen
  wrong:

  const { defineConvexZen } = require('convex-zen');

  correct:

  import { defineConvexZen } from 'convex-zen';

  Used in `convex/zen.config.ts` to configure authentication; `convex-zen` primarily targets modern ESM environments, making CommonJS `require` generally incorrect.
• ConvexProviderWithAuth
  wrong:

  import { ConvexProviderWithAuth } from 'convex-zen';
  import ConvexProviderWithAuth from 'convex-zen/tanstack-start';

  correct:

  import { ConvexProviderWithAuth } from 'convex-zen/tanstack-start';

  Framework-specific providers for integrating with a particular UI framework (e.g., Next.js, Tanstack Start, Expo) are exposed via dedicated subpath exports. Ensure you import from the correct subpath for your project.
• useConvexAuth
  wrong:

  import { useConvexAuth } from 'convex-zen/client'; // Incorrect subpath unless explicitly defined
  import { useConvexAuth } from 'convex-zen/next';

  correct:

  import { useConvexAuth } from 'convex-zen';

  General-purpose client-side hooks like `useConvexAuth` are typically exported directly from the main `convex-zen` package, providing core authentication state and actions irrespective of the UI framework adapter.

Quickstart

This quickstart illustrates the essential steps to set up Convex-Zen authentication, including defining provider configurations, integrating with Convex's auth bridge, wiring the framework-specific provider (using Tanstack Start as an example), and executing the necessary code generation step.

npm install convex convex-zen @tanstack/react-start

// convex/zen.config.ts
import { defineConvexZen } from 'convex-zen';

export default defineConvexZen({
  authProviders: [{
    domain: process.env.NEXT_PUBLIC_CLERK_ISSUER_URL ?? '', // Example for Clerk or similar OIDC provider
    appId: process.env.NEXT_PUBLIC_CLERK_APP_ID ?? '',
    clientUrl: process.env.NEXT_PUBLIC_CONVEX_URL ?? '',
  }],
  // ... other configuration like roles, permissions
});

// convex/auth.config.ts
import * as auth from 'convex-zen/auth';
export default auth.config;

// app/root.tsx (Example for Tanstack Start application's root layout)
import React from 'react';
import { Outlet } from '@tanstack/react-router';
import { ConvexProviderWithAuth } from 'convex-zen/tanstack-start';
import { ConvexReactClient } from 'convex/react';

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL ?? '');

export default function Root() {
  return (
    <ConvexProviderWithAuth client={convex}>
      <Outlet />
    </ConvexProviderWithAuth>
  );
}

// After defining configurations and installing packages, run the CLI tool:
npx convex-zen generate