Announcing the Beta Release of nextjs-auth0 SDK v4 🎉

[brth31]

Hello everyone,

We're thrilled to announce the beta release of nextjs-auth0 SDK v4! This new version brings significant improvements, new features, and fixes to enhance your development experience.

⚠️ Important Notice About v3

As we move forward, we will not be updating v3 of the SDK to support Next.js 15. This allows us to focus on v4, which offers a wealth of new features and improvements. This will also enable us to support future releases of Next.js faster and with more confidence. We understand this may pose challenges, and we're here to help.

v3 will continue to receive critical security updates for 6 months after the GA of v4.

📣 Highlights of v4 Beta

• Middleware-Based Authentication: Improved compatibility and reduced maintenance by moving to middleware-based handlers.
• Enhanced Security: Switched to encrypted cookies and removed outdated cookie logic.
• Resolved State Mismatch Issues: Fixed long-standing issues reported by the community.
• Improved Session Management: Implemented rolling sessions and eliminated cookie chunking.
• Improved Hooks and Helpers: Introduced useUser(), getAccessToken(), and getSession() for easier data fetching and session handling.
• Stateful Sessions with Custom Databases: Support for "Bring Your Own Database" (BYODB).
• Compatibility with Next.js 15, Turbopack, and React 19
• Simplified architecture, API, and configuration options

✍️ Try It Out and Provide Feedback

We invite you to explore the beta release and share your feedback to help us improve before the general availability release. We are currently targeting a general availability release by the end of December.

Beta Release: v4.0.0-beta.3

⛵ Need Help with Migration?

If you encounter challenges migrating to v4, please don't hesitate to open an issue and our team will assist you. We're committed to making the transition as smooth as possible.

Thank You for Your Support 🙌

We appreciate your understanding as we focus on making v4 the best it can be. Your feedback is invaluable, and we're here to support you every step of the way.

Happy coding! 🚀

— The Auth0 DX SDK Team

[curry1337]

Thank you for the beta release! Do you have any migration documentation or best practices available?

[brth31]

@curry1337 we do have a comprehensive documentation that you can refer to- https://github.com/auth0/nextjs-auth0/blob/v4/README.md. Hope this helps!

[johncarmack1984]

@brth31 The documentation is lacking a coherent migration strategy for those using earlier versions; so far advice from the only auth0 engineer in these threads has delivered application-breaking fixes that actually made our application less secure. I would disagree with the use of the word "comprehensive" in your previous comment, and I disagree with a product strategy that ignores what paying customers are telling you about this release's clear unreadiness for use in production environments.

[curry1337]

@brth31 Thanks, what about the Edge Runtime? Couldn't find anything about it in the Readme.
We now use @auth0/nextjs-auth0/edge in the middleware.

Is import { Auth0Client } from "@auth0/nextjs-auth0/server" replacing the old edge?

[johncarmack1984]

@curry1337 not representing auth0 or Vercel, but happy to help a fellow engineer: Vercel reverted all edge rendering back to Node.js seven months ago, so the distinction is currently moot from a practical standpoint (although the Edge API remains in the Next.js docs, so Edge rendering may return in time, so it makes sense you would want the auth0 adapter to ensure support for it). Hope this helps you and your team plan for the future!

[curry1337]

@johncarmack1984 Wow thanks so much for sharing, really appreciated!

[mitchheddles]

Is there, or will there be, a way to use this without middleware? Middleware only feels like more of a limitation, rather than a "feature".

Update: After some testing, it seems like we're able to use the export const GET = auth0Client.middleware; in a route handler, as long as the routes match, e.g. /src/app/auth/[auth0]/route.ts. It doesn't feel right, but it's good enough for now.

[portal7]

I have tried (albeit a bit “commending myself to god”) to implement from 0 in a totally clean project using the initial steps indicated in the “getting started” article of NextJS 15.

I followed the steps they mention in v4 beta, but not only is it not entirely clear, but it didn't work for me.
as you can see in the attached image.

Is there any place where you can give a “practical” example or a test repo, or a sandbox to see how you implement it?
Thanks

[MrUprizing]

Hi @portal7, I have a project that will be deployed to NextJs 15, and the Auth0 SDK is delaying us. We're going to wait for version 1.0 of SDKv4. In the meantime, I created a basic example to see how it works. You can check it out to get an idea.
https://github.com/uprizingFaze/NextJs_15-Auth0_V4

[portal7]

Hi @portal7, I have a project that will be deployed to NextJs 15, and the Auth0 SDK is delaying us. We're going to wait for version 1.0 of SDKv4. In the meantime, I created a basic example to see how it works. You can check it out to get an idea. https://github.com/uprizingFaze/NextJs_15-Auth0_V4

Thanks!!! I really appreciate it, I'm going to try it out and then.... we'll see.

[portal7]

Well, I downloaded it and tried to run it, but I have not been able to get it to work.

(unfortunately, I don't have enough experience in JS development to be able to go deeper and investigate what would be the problem).

[MrUprizing]

Oh, this is because of npm i, many packages need to specify the version of React 19 to avoid that issue.
Just use npm i --force when using Next.js 15 or any React 19 project (if you use pnpm, Bun, or Yarn, I think this isn't necessary). Here’s a brief explanation

[portal7]

@uprizingFaze , thanks for the clarification, I will read the explanation to improve my knoweldge.

After rename and fil the values inside the .env.local values was able to run it with any other console error.

But....

Same as my capture with a fresh-started project with the new package installed.

[MrUprizing]

It is likely due to the Auth0 environment variables or the URLs in the Auth0 dashboard.

Check this

Dashboard of my example:

[portal7]

Well, after configuring the variables again in auth0 with the indicated values (I registered a new app so as not to modify what I had) and it worked.

The strange thing was that when I clicked on logout, I got an error that the value of the logout URL that I had passed was not valid.

And this is my configuration on Auth0

this was fixed when I added http://localhost:3000 (what the Auth0 error page said) as an enabled value.
Note: I am using beta-3 version, I don't know if this is solved in version 7, but I will try it.

Thanks @uprizingFaze
I strongly appreciate your time and the help/guidance you have given me.

[ctcooper]

@portal7 Did you make sure your app in Auth0 is set as a 'Regular Application'?

'Settings -> Application Properties -> Application Type -> Regular Web Application'

[portal7]

Hi @ctcooper ,
No, the value selected in Auth0 was Single Page (SPA)

[paradimes]

Hi @ctcooper , No, the value selected in Auth0 was Single Page (SPA)

for next, you should use Regular Web Application:

[jamiebytebender]

Is there any example of the new v4 working with org invitations?
I have a solution similar to this #701 (comment) where I was calling handleLogin previously but on the latest version there is no handleLogin exported.

[willedanielsson]

@curry1337 we do have a comprehensive documentation that you can refer to- https://github.com/auth0/nextjs-auth0/blob/v4/README.md. Hope this helps!

Hey, any news on a migration guide?
Like
"Rename env variable XX to YY" etcetera so it's easy to migrate and that people can propose updates to?
As someone going from 3 to 4 due to requirement for Nextjs, it would be good with a migration guide and not an installation guide 🙌

[curry1337]

@brth31 Could you please provide an update on when we can expect the stable release of v4? Our team has decided to wait for the stable release and not rely on the beta version.

[brth31]

@curry1337 we are tentatively aiming to go GA later this month. I will share more updates closer to the release date.

[curry1337]

@brth31 Great! Thank you for replying so quickly.

[neptaco]

When I retrieve the AccessToken, the Payload section is missing. Is this issue occurring for anyone else? This happens both when setting up from scratch with beta9 and accessing /auth/access-token, as well as in projects updated from v3.5.0. In both cases, the Payload section is missing.

[mcgaryes]

@neptaco - I was not seeing the payload until I overwrote the beforeSessionSaved property. I also changed my audience in authorizationParameters to get the accessToken back in a JWT format.

export const auth0 = new Auth0Client({
    async beforeSessionSaved(session) {
        return {
            ...session,
            user: {
                ...session.user,
            },
        }
    },
    authorizationParameters: {
        audience: "https://service.com", // service that I was needing a JWT for 
    },
});

[neptaco]

@mcgaryes
Thank you for the information!
I tried it, and in my case, I was able to retrieve the information just by setting the audience.

In v3.5.0, I used the environment variable AUTH0_AUDIENCE for the configuration, but in v4, it seems that this setting is no longer applied via environment variables.

I’m not sure whether this change is intentional in v4 or if it’s a bug where environment variables are not being loaded.

[chris-erickson]

@mcgaryes Thank you for the information! I tried it, and in my case, I was able to retrieve the information just by setting the audience.

In v3.5.0, I used the environment variable AUTH0_AUDIENCE for the configuration, but in v4, it seems that this setting is no longer applied via environment variables.

I’m not sure whether this change is intentional in v4 or if it’s a bug where environment variables are not being loaded.

Docs seem to indicate this is now configured with manually setting up the client. Would be good for the migration one to indicate this needs to be adjusted if so!

Wondering as well if it's contributing to this error (that we're also seeing, but slightly different, can open a new issue as needed): #1841 (comment)

TypeError: Failed to parse URL from /auth/access-token.

Update: This seems to be not influencing to aforementioned bug. #1843

[jdwitten]

I also stumbled on the audience issue. Needed to supply it in the auth0 client initialization like @mcgaryes mentioned to get a valid payload in the JWT access token. Would be good to document this in the migration guide if it is intended.

[brth31]

@jdwitten apologies for the delay. Security review and other release readiness tasks are taking us more time than we anticipated. We are unable to rush through these tasks considering this is a major version release with significant changes to the SDK internals.

We're trying out best to release the GA this week. I appreciate your patience here.

[jdwitten]

Thanks for the update @brth31 👍

[chammond3]

I would love a vanilla example of v4 working properly. I'm following the steps in the v4 fork and struggling to get an error of Error [TypeError]: Invalid URL from return await auth0.middleware(request) in middleware.

I have a basic nextjs project using the app router that I recently built and trying to prove out auth0. I had v3 working with the exception of the getSession breaking change in next 15. I'm really spinning my wheels converting to v4...

[brth31]

🎉 v4 is now GA. Thanks for your patience, everybody!

[kylemorena]

Hello, does the latest version support Preview URLs and Branch URLs on Vercel?
The issue is having different domains, causing the redirect URI to mismatch.

Use a * in the domain to add the Vercel URLs to your Allowed ____ URLs. It'd be something like https://*-my-project.vercel.app. Probably smart to not do https://*.vercel.app as that'd let any Vercel account use your stuff.

Hi,
thanks for replying!
the issue I'm facing is managing VERCEL_BRANCH_URL and VERCEL_URL. I'm using VERCEL_URL as the appBaseUrl. Is there an alternative way to handle this? In version 3, I was able to build the redirectUri by retrieving the request host(request.nextUrl.origin) from the API route handler in Next.js.

[jamiebytebender]

I have similar issue @kylemorena with preview deployments.
I was also using the following in the .env.production NEXT_PUBLIC_AUTH0_BASE_URL=${VERCEL_URL:-$VERCEL_BRANCH_URL} but doesn't seem to work anymore.

[KrustyC]

🎉 v4 is now GA. Thanks for your patience, everybody!
@brth31 Thanks for getting this over the line. I have a question though:

Is there a plan to actually release this on NPM as well? Seems like the latest available version on NPM is not an official one, but it's just a beta?

[isoroka-plana]

🎉 v4 is now GA. Thanks for your patience, everybody!
@brth31 Thanks for getting this over the line. I have a question though:

Is there a plan to actually release this on NPM as well? Seems like the latest available version on NPM is not an official one, but it's just a beta?

@KrustyC there's 4.0.0 in the version history so I am pretty sure you can install it.

Question is why is it not among the current tags instead of the beta one?

[chris-erickson]

It's also still only in the v4 branch instead of main which is incredibly confusing when coming back here to look for v4 docs. Takes some time digging into PR's to really even be sure that's that correct branch.

[curry1337]

Fellow developers who have migrated: What’s your advice for others? Should we move to v4 now or hold off? We’re planning to upgrade to Next.js 15 but want to avoid debugging Auth0, as our roadmap is already packed.

[chris-erickson]

Would reccomend. Overall it works much more like you'd expect and no major issues detected here. Glad to have NextJS 15 features.

[curry1337]

Would reccomend. Overall it works much more like you'd expect and no major issues detected here. Glad to have NextJS 15 features.

Thank you!

[DotCoyote]

Fellow developers who have migrated: What’s your advice for others? Should we move to v4 now or hold off? We’re planning to upgrade to Next.js 15 but want to avoid debugging Auth0, as our roadmap is already packed.

Overall it works quite good, I just ran into an edgecase: #1884

[perryraskin]

@chammond3 I'm having the same issue as you - Invalid URL happening in the middleware file. I'm on v4.0.1. Is there a solution? I have the correct env variables so I'm not sure what the issue is.

UPDATE: It appears that changing the env var from AUTH0_BASE_URL to APP_BASE_URL did the trick.

[mmeadwell]

Has anyone implemented a custom session store using redis or a database? Reading through the documentation I see how to setup the custom session store but not any implementation details. Thanks for any help in advance!

[jonkwheeler]

Excited about the release. Anyone else having issues with the search bar on the docs site? https://auth0.github.io/nextjs-auth0/modules.html

[avaldez-gr]

The amount of changes is substantial with no migration guide. This is extremely frustrating considering my company is spending a substantial amount of money for this. No way to get roles anymore - at least not clearly - because there is no idToken, just an access token. And, even with this, there's no documentation on how to obtain the roles from this.

Cool new features, but the roll out is pretty rough.

[jonkwheeler]

Where are the docs for v3?

[calvinbrewer]

Where are the docs for v3?

@jonkwheeler Older README versions can be found on the tagged releases. E.g. https://github.com/auth0/nextjs-auth0/tree/v3.6.0

[jonkwheeler]

Where are the docs for v3?

@jonkwheeler Older README versions can be found on the tagged releases. E.g. https://github.com/auth0/nextjs-auth0/tree/v3.6.0

Yeah, but that's not the full docs. Try following those links. All broke now.

I'm pretty sure I've exposed that screen_hint does nothing. I was trying to find docs on it. I'm stuck just reading the source code instead.

[jonkwheeler]

Cool new features, but the roll out is pretty rough.

Has anyone had a positive experience? Wondering if I attempt the jump now that all v3 support is dropped, and I also can't use Next.js v15 unless I upgrade this now. (OR I fork v3)

[avaldez-gr]

Cool new features, but the roll out is pretty rough.

Has anyone had a positive experience? Wondering if I attempt the jump now that all v3 support is dropped, and I also can't use Next.js v15 unless I upgrade this now. (OR I fork v3)

@jonkwheeler we just updated to Next15 and we're forced to use v4. It was painful but we figured it out. It's pretty frustrating there's little documentation on this and the documentation is missing some key items. With v3 you use the api but with v4 you have to use middleware. I do like it better, but that's just because we figured out how to use it. Lots have changed. Can't use the same exported members as before. And have to create your own lib instantiating auth0.

Metadata is no longer along with the user data. So you have to use the management sdk to get any data from metadata.

[brentshulman-silkline]

This is ridiculous. That lack of follow-up and response from the Auth0 team here is borderline negligent. I'm pissed off, and you should be too.

Luckily, the original poster, @brth31, generously gave us his Calendly link on his Github profile. I set a meeting with him, and if you feel the same way I do, I encourage you to do the same.

For example, is this the migration guide we are looking for? Hell if I know.

[chris-erickson]

Cool new features, but the roll out is pretty rough.

Has anyone had a positive experience? Wondering if I attempt the jump now that all v3 support is dropped, and I also can't use Next.js v15 unless I upgrade this now. (OR I fork v3)

Took about a day to migrate a not very complicated site and it's been fine. The communication and documentation has left a lot to be desired and pushed us to seriously explore alternates because it's been so rocky. Just an incredible unforced error.

[brth31]

Sincere apologies for the radio silence here 🙏 The team probably had no visibility on the recent comments since the issue was marked as closed. I'm re-opening this issue and paging @tusharpandey13 and @arpit-jn for visibility.

My calendly link is still open for anybody who is willing to share feedback on any of our SDKs. I'm also happy to do working sessions with our engineering team to solve your integration problems. Please add a note while booking the meeting, so that we can come prepared.

Again, I really appreciate your patience here. We're working really hard to action all the feedback across other GitHub issues on this repo. In the spirit of transparency, here's the prioritised list of problems we're tackling for the upcoming releases:

1. Server Component Token Management (#1718)
2. Native Re-authentication Support (#1920 and #1937)
3. Improved cookie management with support for built-in cookie splitting mechanisms
4. Support for Partial Prerendering (PPR)
5. Edge Runtime Support (#1908)
6. Improved User Creation Workflow (#1759 )

In the upcoming weeks, you should see us making progress on the above issues. Happy to prioritise any other issues that are top of mind for you.

[brad-decker]

I have an onboarding modal that only shows up if the useUser hook returns a user with an email property that isn't 'typeof user?.email === 'undefined'' if there is an email, it will popup the modal IF the returned user object from the database doesn't have provided data that is needed by our application.

What i'm experiencing since adopting 4.1 is that after sometime of being on the site sometimes the modal will pop up for a user - and after refreshing the user is no longer logged in. Its difficult to reproduce cause it requires some kind of session expiration to happen but i'm unsure of what is causing that expiration. Anyone have advice or suggestions on what may be the cause?

EDIT: Setting 'absolute' and 'inactivity' durations low (1 second) doesn't trigger the same experience locally

[jonkwheeler]

In case it helps anyone, we decided we couldn't wait around for Auth0 to fix itself. After looking at WorkOS and Descope, we went to Descope. The experience has been quite nice. They have a Slack Community called AuthTown you can join and ask questions.