loginrocket.js

The loginrocket.js library is for the LoginRocket API, which is our API for untrusted clients like web browsers and mobile apps. It does not require exposing an API key.

For backend (server-side) apps which are able to properly protect an API key, see authrocket-node.

loginrocket.js is designed to work with a wide variety of JS frameworks, including React, Angular, Vue, Svelte, Stimulus, and even jQuery, as well as vanilla Javascript.

For our Getting Started guide, see Integration with Client-side JS.

Installation

If you use a bundler like npm or yarn, install the package as usual with one of:

npm install @authrocket/loginrocket

yarn add @authrocket/loginrocket

Client Basics

Configuring the client

To initialize the LoginRocket client, the AuthRocket Realm’s LoginRocket URL is required.

LoginRocket URLs based on custom domains are supported.

import LoginRocket from '@authrocket/loginrocket'
const loginrocket = new LoginRocket({
  url: 'https://SAMPLE.e2.loginrocket.com/'
})

While it should be rare, in a more advanced multi-tenant setup, the LR URL can be changed between requests.

console.log('Current URL', loginrocket.lrUrl)

loginrocket.lrUrl = 'https://OTHER.e2.loginrocket.com'

Localization

By default, the LoginRocket API will intelligently set the locale based on the user’s browser and other available settings.

However, if you provide a direct way for users to change locales, you’ll probably want to set LoginRocket’s locale based on your app’s existing locale setting to ensure a consistent experience for your users. To do so, add the optional locale argument.

Successful (status 2xx) responses and field/data validation errors (status 409 and 422) are localized.

See Localization for available locales and other details.

const loginrocket = new LoginRocket({
  url:    'https://SAMPLE.e2.loginrocket.com/',
  locale: 'en'
})

The locale can also be retrieved or changed between requests.

console.log('Current locale', loginrocket.locale)

loginrocket.locale = 'es'

Requests

All requests return Promises and are compatible with async/await.

See the LoginRocket API documentation for available APIs and parameters.

Responses

All response payloads are JSON objects with a result key, including errors originating from the LoginRocket API. The only times you should receive a Javascript exception are browser and network errors.

loginrocket.someRequest({...})
  .then(response => {
    // All API server responses, both success and error
    // On error, response.result == 'error'
    ...
  }).catch(error => {
    // Only browser or network errors.
  })

Details on response payloads are in the LoginRocket API, including possible values for result.

Also see our extensive processResponse example that’s part of Logins with JS.

Error responses

Field/data validation errors (status 409 or 422) return a JSON object with result == 'error' and data-specific, localized error messages. These are typically field errors, such as “Email is invalid.”

All other 4xx and 5xx errors are normalized to match, and return the same style response plus an added source key which is based on the original HTTP status. The included error messages are not localized, so if that’s important, rely on source instead.

response.error is a single string, with all errors, suitable for display to the user. Similarly, response.errors is an array of one or more strings, also suitable for display to the user.

loginrocket.someRequest({...})
  .then(response => {
    if (response.result == 'error') {
      if (response.source) {
        // 4xx or 5xx, except 409, 422
        response.source // => "AccessDenied"
        response.error  // => "Session expired or access denied."
        response.errors // => [ "Session expired or access denied." ]
      } else {
        // 409 or 422
        response.error  // => "All errors as sentences. And in a single string."
        response.errors // => [ "All errors as sentences.", "But as an array of strings." ]
      }
    } else {
      // 2xx - use response.result to determine action
    }
  }).catch(error => {
    // Browser or network errors
  })