Step 10 sample code for Clerk auth violates React rule: never pass Hooks as values

[SuperJakov]

Summary

The code shown in Step 9 of the Clerk integration guide passes the useAuth Hook itself as a prop, which violates the React rule:

Never pass around Hooks as regular values
— React docs

This can disable future React Compiler optimizations and complicates static analysis.

Problem location

File: /npm-packages/docs/docs/auth/clerk.mdx Line 334
Section: Step 9: Configure ConvexProviderWithClerk

Current snippet:

<ConvexProviderWithClerk client={convex} useAuth={useAuth}>

useAuth is a Hook, but it is being passed as a plain value (useAuth={useAuth}).

Root cause & correct pattern

useAuth must be called inside a component that is already wrapped by <ClerkProvider>.
Therefore we need two components:

1. A leaf component that renders <ConvexProviderWithClerk> and calls useAuth() inside it.
2. A root provider that wraps everything in <ClerkProvider>.

This satisfies both:

• React Rules of Hooks
• Clerk’s requirement that useAuth() be used within <ClerkProvider>

Suggested fix

React example

Replace the single provider file with:

// convex-client-provider.tsx
"use client";
import { ReactNode } from "react";
import { ConvexReactClient } from "convex/react";
import { ConvexProviderWithClerk } from "convex/react-clerk";
import { useAuth } from "@clerk/clerk-react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

export default function ConvexClientProvider({ children }: { children: ReactNode }) {
  const auth = useAuth();               
  return (
    <ConvexProviderWithClerk
      client={convex}
      useAuth={() => auth}              
    >
      {children}
    </ConvexProviderWithClerk>
  );
}

and in your root:

// main.tsx (or App.tsx)
import { ClerkProvider } from "@clerk/clerk-react";
import ConvexClientProvider from "./convex-client-provider";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <ClerkProvider publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}>
      <ConvexClientProvider>
        <App />
      </ConvexClientProvider>
    </ClerkProvider>
  </React.StrictMode>
);

Impact

• Keeps the sample compliant with React rules
• Avoids potential React Compiler warnings / optimisation failures
• Requires no breaking changes to the <ConvexProviderWithClerk> API

Happy to open a PR if this looks good!

[SuperJakov]

Sorry guys, I'm not really that familiar with creating Github issues so it's not that good. I hope you understand what I mean.
The docs have 2 parts where this code is used: Vite (step 9) and Next.js (step 10) so we have to replace both.

[thomasballinger]

Hi @SuperJakov, is there a React compiler error or misbehavior you're seeing because of this? Or a linter error? I want to make sure we can repro, sounds like this is starting to matter for the first time and we might need to design a new interface here?

[SuperJakov]

Sure, I'll give you reproduction steps using the official convex/next.js/clerk example:

1. git clone https://github.com/get-convex/template-nextjs-clerk.git
2. npm install
3. npm install eslint-plugin-react-compiler --save-dev - Downloads react compiler eslint rules
4. Modify the eslint.config.mjs to use the installed rules:

import { dirname } from "path";
import { fileURLToPath } from "url";
import { FlatCompat } from "@eslint/eslintrc";
import reactCompiler from "eslint-plugin-react-compiler";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const compat = new FlatCompat({
  baseDirectory: __dirname,
});

const eslintConfig = [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  reactCompiler.configs.recommended,
];

export default eslintConfig;

5. Run npm run lint and get this error in terminal:

> my-app@0.1.0 lint
> next lint


./components/ConvexClientProvider.tsx
15:55  Error: Hooks may not be referenced as normal values, they must be called. See https://react.dev/reference/rules/react-calls-components-and-hooks#never-pass-around-hooks-as-regular-values  react-compiler/react-compiler

info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/app/api-reference/config/eslint#disabling-rules

[SuperJakov]

I recommend just passing what the useAuth hook returns. That doesn't break rules and is still readable! However, that means that ClerkProvider will be a bit higher up in code