{"id":16717,"library":"convex-zen","title":"Convex-Zen Authentication Component","description":"Convex-Zen is a production-grade authentication component designed for applications leveraging the Convex backend. Currently at version 1.13.5, it offers a robust, reusable auth solution. The package is actively maintained with frequent releases, typically multiple bug fixes and dependency updates within a month, reflecting ongoing development. Its key differentiator from Convex's 'Better Auth' integration is that Convex-Zen implements native authentication logic directly within Convex component functions, rather than importing an external runtime into app code. It provides framework-specific exports, allowing seamless integration with popular environments like Next.js, Tanstack Start, and Expo, while exposing a consistent and familiar API surface for developers.","status":"active","version":"1.13.5","language":"javascript","source_language":"en","source_url":"https://github.com/natedunn/convex-zen","tags":["javascript","typescript"],"install":[{"cmd":"npm install convex-zen","lang":"bash","label":"npm"},{"cmd":"yarn add convex-zen","lang":"bash","label":"yarn"},{"cmd":"pnpm add convex-zen","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for integrating Convex-Zen authentication components with applications built using Tanstack Start.","package":"@tanstack/react-start","optional":true},{"reason":"Core dependency for any application utilizing the Convex backend, including Convex-Zen's auth components and functions.","package":"convex","optional":false},{"reason":"Required for integrating Convex-Zen authentication components within Next.js applications.","package":"next","optional":true},{"reason":"Fundamental UI library dependency for rendering Convex-Zen's React components.","package":"react","optional":false}],"imports":[{"note":"Used in `convex/zen.config.ts` to configure authentication; `convex-zen` primarily targets modern ESM environments, making CommonJS `require` generally incorrect.","wrong":"const { defineConvexZen } = require('convex-zen');","symbol":"defineConvexZen","correct":"import { defineConvexZen } from 'convex-zen';"},{"note":"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.","wrong":"import { ConvexProviderWithAuth } from 'convex-zen';\nimport ConvexProviderWithAuth from 'convex-zen/tanstack-start';","symbol":"ConvexProviderWithAuth","correct":"import { ConvexProviderWithAuth } from 'convex-zen/tanstack-start';"},{"note":"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.","wrong":"import { useConvexAuth } from 'convex-zen/client'; // Incorrect subpath unless explicitly defined\nimport { useConvexAuth } from 'convex-zen/next';","symbol":"useConvexAuth","correct":"import { useConvexAuth } from 'convex-zen';"}],"quickstart":{"code":"npm install convex convex-zen @tanstack/react-start\n\n// convex/zen.config.ts\nimport { defineConvexZen } from 'convex-zen';\n\nexport default defineConvexZen({\n  authProviders: [{\n    domain: process.env.NEXT_PUBLIC_CLERK_ISSUER_URL ?? '', // Example for Clerk or similar OIDC provider\n    appId: process.env.NEXT_PUBLIC_CLERK_APP_ID ?? '',\n    clientUrl: process.env.NEXT_PUBLIC_CONVEX_URL ?? '',\n  }],\n  // ... other configuration like roles, permissions\n});\n\n// convex/auth.config.ts\nimport * as auth from 'convex-zen/auth';\nexport default auth.config;\n\n// app/root.tsx (Example for Tanstack Start application's root layout)\nimport React from 'react';\nimport { Outlet } from '@tanstack/react-router';\nimport { ConvexProviderWithAuth } from 'convex-zen/tanstack-start';\nimport { ConvexReactClient } from 'convex/react';\n\nconst convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL ?? '');\n\nexport default function Root() {\n  return (\n    <ConvexProviderWithAuth client={convex}>\n      <Outlet />\n    </ConvexProviderWithAuth>\n  );\n}\n\n// After defining configurations and installing packages, run the CLI tool:\nnpx convex-zen generate","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure you use the correct subpath import for your framework, such as `import { ConvexProviderWithAuth } from 'convex-zen/next';` or `convex-zen/tanstack-start`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.13.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"Module not found: Can't resolve 'convex-zen/next'"},{"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.","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.","error":"TypeError: (0 , _convex_zen_next__WEBPACK_IMPORTED_MODULE_0__.ConvexProviderWithAuth) is not a function"},{"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.","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.","error":"Convex client not initialized. Make sure you have wrapped your app in a <ConvexProvider>"}],"ecosystem":"npm"}