developers

Auth0 SDK for Single Page Applications v2.0 released!

Let's explore the main features of the new Auth0 SDK for SPA release.

Juan Cruz Martinez

Staff Developer Advocate

Nov 10, 2022 • 6 min read

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:

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!