convex-zen

library1.13.5jsnpmunverified

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.

auth-security web-framework

npm install convex-zen

github ↗package ↗

INSTALL

IMPORT

SIG · CONVEX-ZEN

convex-zen

auth-securityjavascriptv1.13.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConvexZen

✓ import { defineConvexZen } from 'convex-zen';

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

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

ConvexProviderWithAuth

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

✗ import { ConvexProviderWithAuth } from 'convex-zen'; 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

✓ import { useConvexAuth } from 'convex-zen';

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

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.

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

Debug

Known issues

breakingConvex-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.

affects: >=1.0.0

gotchaFramework-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`.

affects: >=1.0.0

gotchaProper 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.

affects: >=1.0.0

gotchaConvex-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.

affects: >=1.13.1

Errors

Common errors & fixes

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

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

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>

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.

Upgrade

Version history

1.13.5latest on npm

Audit

Dependencies

@tanstack/react-startoptionalRequired for integrating Convex-Zen authentication components with applications built using Tanstack Start.

convexrequiredCore dependency for any application utilizing the Convex backend, including Convex-Zen's auth components and functions.

nextoptionalRequired for integrating Convex-Zen authentication components within Next.js applications.

reactrequiredFundamental UI library dependency for rendering Convex-Zen's React components.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/natedunn/convex-zen ↗

packagehttps://www.npmjs.com/package/convex-zen ↗