A Guide To Auth0 Apps on Cloudflare: V8 Runtime Adoption

This guide explores developing Auth0 applications on Cloudflare Pages, focusing on the transition from Node.JS to the V8 runtime and its impact on JavaScript frameworks like Next.JS.

The proliferation of V8 runtime has meant that many libraries are not compatible, including Auth0 libraries. We conclude that using Auth0 SPA libraries, which are edge-compatible, alongside a SPA deployed on Cloudflare Pages is the simplest approach.

History of Javascript in Cloudflare Pages and Workers

Cloudflare Pages was initially designed to serve static assets, enabling the functionality of JavaScript applications that run client-side. A downside to Single Page Applications (SPAs) was the many requests to backend APIs, contributing to latency and potentially diminishing user experience.

To counter this, many JavaScript frameworks began offering server-side rendering (SSR). This pre-renders dynamic content before it’s delivered to the client, thereby reducing round trips. Frameworks like Next.JS were developed with the understanding that they would always run on a Node.JS host.

Cloudflare Pages and Workers utilize the V8 runtime, which is not Node.JS. As a result, Cloudflare wasn’t compatible with these frameworks. However, there has been a recent shift towards experimental “edge” deployments that don’t rely on Node.JS, creating compatibility with Cloudflare and other similar platforms.

However, this transition has added to the confusion for developers. In Next.JS, particularly for beginners or when starting with boilerplate examples, it can be a challenge to determine if a swap to the edge API is necessary. Fundamentally there just aren’t enough examples around yet that work seamlessly.

Breaking it Down: Cloudflare and V8 Compatibility

Cloudflare is restricted to the V8 runtime, implying that any library expecting Node.JS will likely fail. There is a compatibility mode available aiming to dynamically migrate Node.js methods to V8, but this often leads to issues.

This necessitates that any technology you use, be it plain JavaScript, SPA, or SSR, must be compatible with V8. Traditional frameworks are at a crossroads, with some refactoring to use the edge runtime. Yet, this transition is often confusing and results in breaking changes, leading to less-than-ideal developer experience.

Auth0 and Edge Compatibility

Auth0 has excelled in developing easy-to-use libraries. However, the shift to edge has led to compatibility issues for many of these. Libraries like nextjs-auth0 or express-openid-connect don’t function in edge mode, as they are reliant on the Node.JS API.

What Libraries Can We Use?

It’s hard to know for sure which combination of libraries will work, because the permutations are vast. But I’ve found that creating an Auth0 Application in SPA mode, and therefore using one of the SPA libraries, can work well. These typically depend on auth0-spa-js, which is edge compatible.

For non-SPA applications, you may be able to use the lower-level auth0-spa-js library, but I found it hard to integrate.

Setting up Auth0 with Cloudflare

Once the Auth0 library has been selected, the create-cloudflare-cli can be used to bootstrap a Cloudflare-compatible project structure with a specific JS framework. Cloudflare assumes you’re providing a SPA if you don’t upload a 404.html file.

In practice, this involves running npm create cloudflare@latest, selecting your preferred framework (React, for example), fixing any broken code, installing @auth0/auth0-react, and following the provided instructions to add the Auth0Provider to your app. Using SPA mode requires specifying cacheLocation="localstorage" to the Auth0Provider settings to leverage browser local storage, ensuring logins persist across refreshes.

What Next?

Making the auth0-react library work with other derivatives, like Next.JS, may be possible, but a friendly library isn’t available yet. You also need to grapple with the edge transition, which can be a challenging developer experience.