Auth0 SDK for Single Page Applications v2.0 released!

The Auth0 team released the new Auth0 Single Page App SDK v2.0, and it's now available in the npm registry. It is a major new release with a focus on development and user experience.

The new release makes an important step towards improving usability and reducing the footprint (size) of the SDK.

Quick Start with the New SDK

You can follow the quick start guide if you build a new application or connect your SPA with Auth0 using the SDK for the first time.

If you use frameworks such as React, Angular, or Vue, you can use framework-specific libraries instead. You can learn more about specific frameworks in our SPA guides section.

All of the mentioned improvements will be available in the next beta versions of our framework-specific SDKs. Be sure to keep an eye on them to be notified when their beta versions are available.

Migrating from v1.x

With the improvements from v1.x, it was necessary to introduce some breaking changes. We will cover the most impactful changes in this post, but we recommend reviewing the migration guide for the details of all breaking changes and their corresponding migration path.

Reduced Bundle Size by 60%

Auth0 SPA SDK V1.x shipped with built-in polyfills to compensate for the lack of native support on some browsers for features such as:

• AbortController
• Promise
• TextEncoder & TextDecoder
• Fetch

As the above APIs are now available for most browsers, we believe there's no more need to include those polyfills. Primarily users of IE11 would require them, and with Microsoft dropping support for IE11, we believe it makes sense to capitalize on the gains and drop support for IE11 as of V2.

By removing these polyfills, and with some small improvements on our side, we reduced the bundle size by an outstanding 60%.

Such a reduction will allow for faster download and processing times for application users.

API Consistency

Our SDK offers a variety of settings that can be divided into two categories:

• Properties used to configure our SDK
• Properties used solely to pass through to Auth0

In v1.x, passing both types of properties to the SDK was possible when instantiating a new Auth0Client. Because the different types of arguments were differentiated only by the case (camel vs. snake case), with no additional separation in the object argument, it wasn't very evident what arguments were SDK properties and which ones were authorization parameters.

Here is an example of what setting such options on v1.x looks like:

const client = new Auth0Client({
  client_id: '...',
  useRefreshTokens: true,
  useRefreshTokensFallback: false,
  redirect_uri: '...',
  custom_param: '...',
  screen_hint: 'signup'
});

With v2, we are ensuring the distinction between the two categories is clear by putting any property solely used to pass through to Auth0 in a property bag named authorizationParams. On top of that, any property outside of authorizationParams will now be using camel casing.

Here is what the configuration looks like in v2:

const client = new Auth0Client({
  clientId: '...', // <= camelCasing
  useRefreshTokens: true,
  useRefreshTokensFallback: false,
  authorizationParams: { // <= new property bag
    redirect_uri: '...', // <= moved into authorizationParams
    custom_param: '...', // <= moved into authorizationParams
    screen_hint: 'signup' // <= moved into authorizationParams
  }
});

localOnly Logout

In v1.x of the SDK, it was possible to pass a localOnly when calling logout. In the current release, we dropped the localOnly argument in favor of a new onRedirect event that allows for more control, including the possibility of not redirecting, and thus produces the same effect the localOnly property intended.

To replicate the localOnly behavior, you can implement the following:

await client.logout({
  onRedirect: async (url) => {
    // Do not do anything
    // Or do something else but redirecting
  }
})

Removed buildAuthorizeUrl and buildLogoutUrl

In v1.x, it was possible to use the methods buildAuthorizeUrl and buildLogoutUrl for applications that couldn't rely on window.location.assign to redirect to Auth0 when calling loginWithRedirect or logout respectively. A typical example of this was when developers needed to set a specific URL in the context of a mobile application using frameworks such as Ionic.

In v2, developers would rely on onRedirect to specify such behavior.

For example:

await client.loginWithRedirect({
  async onRedirect(url) {
    // Redirect using Capacitor's Browser plugin
    await Browser.open({ url });
  }
});

getUser and getIdTokenClaims

As part of our optimization efforts, we reworked the SDK's internal cache to store tokens. Consequently, it was possible to simplify the methods getUser and getIdTokenClaims.

In v1.x, developers could pass a specific scope and audience when calling either of those functions.

Here are some examples of how these functions were used in v1:

const user = await getUser();
const user = await getUser({ audience, scope });

const claims = await getIdTokenClaims();
const claims = await getIdTokenClaims({ audience, scope });

However, as an application should only have one user, such parameters wouldn't be required. So from v2, we dropped those parameters and simplified the methods to:

const user = await getUser();
const claims = await getIdTokenClaims();

Retrieve a Token from the Cache

With v2, we are introducing the possibility of retrieving a token from the cache without contacting Auth0 if no entry is found. To achieve that, we reworked the already existing ignoreCache argument for getTokenSilently, which takes a boolean, to cacheMode, which can accept three values:

• on (default value): Use the cache, but call the oauth/token endpoint when no entry is found. This is the equivalent of when ignoreCache was omitted or its value was set to false in v1.
• off: Do not use the cache, always call the oauth/token endpoint. This is the equivalent of ignoreCache: true in v1.
• cache-only: Use the cache, do not call the oauth/token endpoint when no entry is found.

To use our SDK and see if we have a token in the cache without contacting Auth0, you must set cacheMode to cache-only when calling getTokenSilently.

const token = await client.getTokenSilently({
  cacheMode: 'cache-only'
});

URL Encoded Form Data

V1 of SPA-JS defaults to sending payloads using JSON when calling Auth0's oauth/token endpoint, but users can opt-in to send the data as x-www-form-urlencoded instead.

With the release of v2, we will default to sending the requests to the oauth/token endpoint using x-www-form-urlencoded, while users can opt-in to using JSON as needed. Using x-www-form-urlencoded has shown to have a small performance optimization and aligns more with what the spec describes.

Summary

The Auth0 Single Page App SDK v2 improves both the developer and the user experience. On the one hand, it simplifies and makes working with the SDK API easier. On the other hand, it reduces the bundle size, which translates into faster downloads and processing times.

Thanks for reading!