ClerkProvider Should Not Force All Children to Render Dynamically

[magnusriga]

Preliminary Checks

• I have reviewed the documentation: https://clerk.com/docs

• I have searched for existing issues: https://github.com/clerkinc/javascript/issues

• This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.

Reproduction / Replay Link

Na

Publishable key

na

Description

Posting this as a bug, even though it is technically a feature, due to its severity.

Currently, the ClerkProvider forces all child routes to render dynamically.

The documentation states that you can move the provider further down the component tree, to address the issue.

Unfortunately, that is not a viable solution in many cases.

Typically, an app has several protected routes, where a common component (like a navbar) is shown on each route, and that component needs to know whether a user is logged in (e.g. to show certain links). The other components in a route might benefit massively from being statically (build time) rendered.

If certain data fetches are slow, not being able to do the fetch/render build-time, might break the application's usability entirely.

In other words, taking away static rendering across all provider children will drastically impact the performance of the application and in certain cases render it useless.

ClerkProvider states that it needs dynamic routes because it uses headers() (and/or cookies()), which are built-in next functions that opt the entire route they appear in into dynamic rendering.

It is my understanding, and I might be wrong, that those functions can only be used in server components. They read a http request's headers or cookies. As such, they do not make sense, client side.

So, given how those functions work, why would we need to dynamically render all children of the ClerkProvider, if none of those children use server side auth functionality.

As an example, if the navbar mentioned above is a client component, and middleware is used to protect routes, I do not see why headers() or cookies() are needed at all.

To test this, I added the Next.js Route Segment Config option to the top of the top-most layout: export const dynamic='force-static'. This turned the full app back to static rendering, even though it used the ClerkProvider around the top-level layout, has a navbar client component that checks if user is logged in, and has all routes protected with middleware. It still works, both the auth and the app.

So, my questions are:

1. Could you keep static rendering as the default, just as Next does, and only opt routes that need headers() into dynamic rendering?

2. What are the consequences of my solution? Will it work as intended, in the example I gave (where no server side auth functions are used)?

Environment

Latest Clerk and Next is used

[focux]

I just ran into this issue as well, I have my ClerkProvider on my root layout and spent like 5 hours debugging why my static pages were rendering dynamically.

Also, about the solution of moving the ClerkProvider down the component tree, I have some layout components that need the session, like the sidebar and user button.

[magnusriga]

Yep, in most cases it is not a viable solution to move the provider down the tree. You can force everything to be static by following my approach above. However, I think it would be optimal if we could mix and match routes with server and client components that use clerk, after which clerk should only require routes to be dynamic if they contain server components with clerk functions.

[theonlyway]

Oh good to see I'm not alone, I just spent an equal amount of time figuring out why my page wasn't being cached by vercels CDN. I haven't really paid much attention to the page types while I've been developing but the closer I'm getting to release I noticed my home page wasn't being cached and that's because my nav bar conditonally renders an avatar & menu items if the users logged in and since that component is also in the root layout and wrapped by clerk what should be a static home page gets classed as dynamic because of the nav. Forcing force-static on the home page doesn't work because then the auth middleware starts crying (It does work if I remove my navigation component from the root layout).

Given the home page for me is actually the only page that shouldn't be dynamic and everything else relies on auth I can probably eat the loss in performance on the home page because I can't actually think of a way where you would have a navigation rendering stuff conditonally based on weather or not the users logged in and not be dynamic if that nav bar is present on every page.

[magnusriga]

Hey there. You should be able to get it to render statically if you:

1. Only use client-side Clerk functions (i.e. make your navbar a client component and use useUser and/or useAuth )
2. Add export const dynamic='force-static' to the top-most layout

I am using middleware and the client-side auth functions and it is statically rendering.

Re. your last paragraph, there is no reason why the navbar itself can't be dynamically populated on the client side, and everything else is statically rendered on the server. That should work fine, as static rendering creates a React Sever Component Payload build time, which has holes for the client components, and that Payload is saved in for instance Vercel's Full Route Cache build time (if the route is statically rendered).

Also, I am wondering if React / Next.js new Partial Prerendering (PPR) will solve the issue of the entire route being dynamically rendered if a component uses dynamic functions like header and cookies (which Clerks's server side functions use under the hood). With PPR I guess we could slap a Suspense boundary around the component using the server-side functions, like a navbar, resulting in only that being dynamically rendered and streamed once ready. If my guess here is accurate, then we can make the navbar a server component again. Until PPR is released, if you want the site / app to render statically the navbar must be a client component (as far as I know).

[theonlyway]

Ah yep. Moved the avatar to a client side component and could get the page to force-static.

[brycelund]

We just ran into this as well. This is a major blocker for us. We've got pages that have to be statically rendered at build time to make those pages usable. We're so far down the road on our clerk integration that I'm not sure what to do. Seems like there should be a way to authenticate a client-only component without forcing the page to be dynamically rendered. Disabling an entire feature branch of optimizations in next.js doesn't seem like a viable long term solution.

[oasaleh]

Check out Kinde. I went from Authjs, Supabase, Clerk, Lucia, and finally Kinde... I wasted about a month trying each.. If you're already using Clerk, I'd just use Kinde..

[JeremyKennedy]

Thank you for your recommendation. I've checked out all of the above already before Clerk, except Kinde. Kinde seems the most similar to Clerk in terms of implementation, UX, pricing, and such - but with the advantage of no Provider, and also seems to have nicer support for user roles (compared to Clerks org-based roles). Looks pretty good to me. How has it been for you so far?

[magnusriga]

Authjs was completely revamped recently and is supported by Next.js team/Vercel. Full native support for React 19 features. I am using Clerk but will try Authjs next.

[skavinvarnan]

+1 Kinde doesn't have this problem, as you get more manual control

[Pulstura]

Similar boat here, this severely impacts my app's performance due to server-side rendering being forced.

[boicualexandru]

I think this limitation poses a significant challenge as it leads to increased operational costs. The inability to cache the home page (or any other mostly static page) content due to the mandatory wrapping of the entire app in the ClerkProvider not only impacts performance but also might steer potential users away from Clerk.
It's particularly frustrating given the new cool Static shell and Suspense boundaries features introduced by NextJs.

[magnusriga]

I have not looked into the Clerk code base, but I am surprised that the ClerkProvider forces the app to be dynamic. A provider, in the Next.js / React ecosystem, should only affect client components that consume the React context. That is at least how normal React contexts work in Next.js.

[magnusriga]

On another note, I am wondering if the upcoming Partial Prerendering in Next.js and React actually fixes the issue. With that update, it is possible to slap on a Suspense boundary outside a component that uses dynamic functions (header() / cookies(), which Clerk's server functions use under the hood) and everything above the boundary in the tree gets statically rendered.

[BRKalow]

Hi y'all, as mentioned in the OP currently the ClerkProvider relies on using headers() and cookies() to determine the current auth state, which in turn causes all pages that are wrapped in the provider to be dynamically rendered. This allows client components that rely on context to SSR with the correct data. Unfortunately there's not really a way to conditionally rely on headers() and cookies() that would allow us to bypass the de-optimization. We are aware of this and are currently exploring alternative APIs and implementations that avoid the de-opt-by-default situation that ClerkProvider currently introduces.

With that being said, there are strategies that you can currently use to workaround this:

• Move ClerkProvider deeper into the tree - If feasible, consider moving the ClerkProvider out of your root layout and into a separate layout only used by pages that rely on authentication.

• Render ClerkProvider in a client component, wrap in a Suspense boundary - ClerkProvider can be rendered as a client component, and when wrapped in a suspense boundary next is able to continue static generation of the rest of the page. This might look like:

   // provider.tsx
   "use client";
   import { ClerkProvider } from "@clerk/nextjs";
   
   export function Provider({ children }) {
     return <ClerkProvider>{children}</ClerkProvider>;
   }
   
   // layout.tsx
   export default function RootLayout({ children }) {
     return (
       <html>
         <body>
           <nav>
             <Suspense>
               <Provider>
                 <ComponentWithAuthState />
               </Provider>
             </Suspense>
           </nav>
           <main>{children}</main>
         </body>
       </html>
     );
   }

  In this setup, the page would still get statically generated, while the specific auth component in the nav would only render on the client.

We totally understand the current behavior is not ideal and in many cases unexpected as a user. We're also aware of the upcoming PPR feature, which will also be impacted by this. We'll continue to share updates as our explorations progress. Thanks for sharing your thoughts here. 🙏

[BRKalow]

ClerkProvider can render as a client or server component. When it's rendered as a server component, it accesses header() and cookies() to get the necessary auth data for SSR.

[magnusriga]

Ah, got it @BRKalow . So, the below should work, right?

1. Render ClientProvider as a client component
2. Only use client-side Clerk functions (useUser and useAuth), e.g. make sure the navbar is a client component

With the above, no dynamic functions are used, right? Which means the following is true (ref. your example):

1. No need to use the Suspense boundary
2. No need to place the ClerkProviderat a lower level in the tree, it does not affect its children as long as the correct Next.js pattern is used (passing server components to client components as the children prop). With that pattern, components still render on the server where the React Server Component Payload leaves holes for client components. All client components in the app can consume the context, and server components remain unaffected.

[theonlyway]

I would assume at the point of making the ClientProvider a client component you are making a choice to give up on using it on the server side so it's one or the other? Because I imagine the middleware probably wouldn't be too happy about that?

[magnusriga]

Yes, by only using client-side auth functions, I was able to render everything statically. I still use middleware in that setup and it works fine (it does not cause dynamic rendering).

[alrightsure]

Ah, got it @BRKalow . So, the below should work, right?

1. Render ClientProvider as a client component
2. Only use client-side Clerk functions (useUser and useAuth), e.g. make sure the navbar is a client component

With the above, no dynamic functions are used, right? Which means the following is true (ref. your example):

1. No need to use the Suspense boundary
2. No need to place the ClerkProviderat a lower level in the tree, it does not affect its children as long as the correct Next.js pattern is used (passing server components to client components as the children prop). With that pattern, components still render on the server where the React Server Component Payload leaves holes for client components. All client components in the app can consume the context, and server components remain unaffected.

Just wanted to drop in and say this doesn't seem to be the case anymore. If you use ClerkProvider in a client component without a Suspense boundary, it opts the whole route into client-side rendering only.

[nionis]

hello everybody, I've run into the same issue. Here is my solution:

• my project has various static pages (ex: /homepage, /contact) however, in all of them I wanted to display a nav component which shows their authentication status
• I decided, for all static pages the nav component will only display Get Started and not require clerk, this can be done with route groups
• Moved ClerkProvider into the /dashboard layout

layout.ts -> sets Metadata
(static)/
  layout.tsx -> Navigation Component without ClerkProvider
  page.tsx
dashboard
  /layout.tsx ->Navigation Component with ClerkProvider 
  /page.tsx

[BRKalow]

Hi all, as of @clerk/[email protected] rendering ClerkProvider does not force the page to be client-side rendered. However, due to the dynamic nature of auth data, putting it at the top level does opt the page in to dynamic rendering.

You can opt-out of this by placing ClerkProvider in client component or moving the provider further down your component tree, as mentioned. Pages will still get statically generated in this case, and components that rely on authentication data will render on the client. If any of our RSC-compatible components are used (SignedIn, SignedOut, or Protect) the page will be opted-in to dynamic rendering. A Suspense boundary can be used for more granular control and to facilitate support for upcoming features like PPR.

We'll update the docs to call this out, thanks for the feedback!

[realverse]

We are encountering this as well using ^4.29.10.

Our aim is to use Clerk in middleware, in RSC, and in client components, with the ability to have pages render statically when they do not require dynamic data... when we wrap ClerkProvider in a client component (as suggested) and run a build, we get:

Error: Clerk: auth() was called but Clerk can't detect usage of authMiddleware(). Please ensure the following:
- authMiddleware() is used in your Next.js Middleware.
- Your Middleware matcher is configured to match this route or page.
- If you are using the src directory, make sure the Middleware file is inside of it.

This error goes away only when export const dynamic = 'force-dynamic'; is placed into root layout.tsx. But this has the effect of rendering all routes dynamically (even if sub pages have force-static).

Can you advise on correct set-up?

We have a middleware.ts (with some simple publicRoutes set).

Our layout.tsx is...

export const dynamic = 'force-static';
//...
  return (
      <html lang="en">
        <body>
        <AuthProvider appearance={clerkAppearance as any}>
        {children}
       </AuthProvider>
//...

Our AuthProvider is...

"use client"

import { ClerkProvider } from '@clerk/nextjs'

export default function AuthProvider({ children, ...props }) {

  return (
    <ClerkProvider {...props}>
      {children}
    </ClerkProvider>
  )
  
}

[tillka]

Hi,

I had the exact same error yesterday, trying to move ClerkProvider down the tree while also getting rid of 'force-dynamic'. Reading the error message, I figured out that the page trying to use a ClerkProvider-related method (like auth()) needs to be in-scope of the clerk-middleware - which was not in my case.

Have a look at your middleware.ts, specifically at the config. Is the page throwing the error in scope of the matcher function?
E.g., I had to specifically add '/checkout' as this page was calling auth() and throwing the error.

export const config = { matcher: ['/checkout'], };

Maybe that helps.

[oasaleh]

as of @clerk/[email protected] rendering ClerkProvider does not force the page to be client-side rendered. However, due to the dynamic nature of auth data, putting it at the top level does opt the page in to dynamic rendering.

Isn't this self-contrary? "ClerkProvider" does not force the page to be client-side rendered, but it will force its children to dynamically render?

I'm not an expert but can you briefly touch on how other solutions like Kinde are able to do it but not Clerk?

[mpopv]

Would be really helpful to have a blog post or something with stripped-down examples of different patterns and how they affect when and how parts of the page are rendered.

[focux]

Yeah, this is so confusing.

[kieronjmckenna]

I'm experiencing this issue using getStaticProps on pages router. When wrapping the app with ClerkProvider the static props are entirely stripped from being passed into the page - seems like the provider breaks basic usage of a pretty integral part of the pages router. Oddly this doesn't happen on dev server and only happens when visiting the page through a , but works fine if the url is visited directly.

For this page I cannot use dynamic rendering as we're hitting an external api, which is not viable to be pulled on every request.

My fix for this is just to exclude the page from middleware all together. I would assume this breaks the @clerk/next auth but it doesn't.

Would like to see this forced dynamic behaviour removed if possible

[thaian1234]

Any update guys ?

[leonthestag]

This seems to break the Next.js which is SSR by default now meaning the existing tutorial for Next.js is no longer functional, I'm using clerk/nextjs 5.16, and next 14.2.1.

[leonthestag]

Nevermind, I got it to work that wasn't the fault of the SSR, that was just me being a yutz.

[joepetrillo]

Hi all, as of @clerk/[email protected] rendering ClerkProvider does not force the page to be client-side rendered. However, due to the dynamic nature of auth data, putting it at the top level does opt the page in to dynamic rendering.

You can opt-out of this by placing ClerkProvider in client component or moving the provider further down your component tree, as mentioned. Pages will still get statically generated in this case, and components that rely on authentication data will render on the client. If any of our RSC-compatible components are used (SignedIn, SignedOut, or Protect) the page will be opted-in to dynamic rendering. A Suspense boundary can be used for more granular control and to facilitate support for upcoming features like PPR.

We'll update the docs to call this out, thanks for the feedback!

@BRKalow There seems to be no update to the docs regarding this - I am lucky to have found the info here, or else I was not going to continue using Clerk. I'd add it asap and maybe have a deeper explanation regarding how rendering is impacted by other things.

PPR seems like it will help solve the exact issue people are having since we can still use server components that do dynamic things, but not cause the whole segment to be dynamically rendered (server static content immediately, stream in dynamic parts). However, I do still get a bit confused how this differs from existing suspense capabilities.