Release v5.0.0-beta.4 (#1242)

Author: subhankarmaiti

.version

@@ -1 +1 @@
-v5.0.0-beta.3
+v5.0.0-beta.4

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Change Log
 
+## [v5.0.0-beta.4](https://github.com/auth0/react-native-auth0/tree/v5.0.0-beta.4) (2025-07-21)
+
+[Full Changelog](https://github.com/auth0/react-native-auth0/compare/v5.0.0-beta.3...v5.0.0-beta.4)
+
+**💡 Major Refactor**: Version 5.0 features a complete architectural overhaul for improved performance, maintainability, and multi-platform extensibility. Check the [Migration Guide](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md) for detailed upgrade instructions.
+
+**⚠️ BREAKING CHANGES**
+
+- feat: architectural refactor for multi-platform extensibility [\#1233](https://github.com/auth0/react-native-auth0/pull/1233) ([subhankarmaiti](https://github.com/subhankarmaiti))
+
+**Added**
+
+- Fix Documentation Typo: 'retreive' → 'retrieve' [\#1183](https://github.com/auth0/react-native-auth0/pull/1183) ([tinchomengo](https://github.com/tinchomengo))
+- feat: added react native web support [\#1233](https://github.com/auth0/react-native-auth0/pull/1233) ([subhankarmaiti](https://github.com/subhankarmaiti))
+
+**Changed**
+
+- feat(deps): Upgrade React Native to 0.80.1 [\#1237](https://github.com/auth0/react-native-auth0/pull/1237) ([subhankarmaiti](https://github.com/subhankarmaiti))
+
+**Fixed**
+
+- fix(iOS): Fix ephemeralSession parameter type conversion in webAuth [\#1238](https://github.com/auth0/react-native-auth0/pull/1238) ([subhankarmaiti](https://github.com/subhankarmaiti))
+
+**Security**
+
+- chore: pin prettier-related packages to prevent malicious package installation [\#1241](https://github.com/auth0/react-native-auth0/pull/1241) ([subhankarmaiti](https://github.com/subhankarmaiti))
+
 ## [v5.0.0-beta.3](https://github.com/auth0/react-native-auth0/tree/v5.0.0-beta.3) (2025-06-23)
 
 [Full Changelog](https://github.com/auth0/react-native-auth0/compare/v5.0.0-beta.2...v5.0.0-beta.3)

FAQ.md

@@ -9,6 +9,8 @@
 7. [Auth0 web browser gets killed when going to the background on Android](#7-auth0-web-browser-gets-killed-when-going-to-the-background-on-android)
 8. [How to resolve the _Failed to start this transaction, as there is an active transaction at the moment_ error?](#8-how-to-resolve-the-failed-to-start-this-transaction-as-there-is-an-active-transaction-at-the-moment-error)
 9. [How can I prevent the autogenerated redirect_uri from breaking if the applicationId has mixed cases or special characters in it on Android?](#9-how-can-i-prevent-the-autogenerated-redirect_uri-from-breaking-if-the-applicationId-has-mixed-cases-or-special-characters-in-it-on-android)
+10. [Why doesn't `await authorize()` work on the web? How do I handle login?](#10-why-doesnt-await-authorize-work-on-the-web-how-do-i-handle-login)
+11. [Why do my users get logged out frequently? How do I keep them logged in?](#11-why-do-my-users-get-logged-out-frequently-how-do-i-keep-them-logged-in)
 
 ## 1. How can I have separate Auth0 domains for each environment on Android?
 
@@ -262,3 +264,76 @@ If you don't need SSO, consider using `ephemeral sessions` or `SFSafariViewContr
 ## 9. How can I prevent the autogenerated redirect_uri from breaking if the applicationId has mixed cases or special characters in it on Android ?
 
 It is recommended to have your applicationId in lower case without special characters to prevent any mismatch with the generated redirect_uri. But in the scenario where you require your applicationId to be of mixed case, to avoid any mismatch , the user can pass a `redirectUri` which matches the one provided in the manage dashboard as part of the `AgentLoginOptions` property.
+
+## 10. Why doesn't `await authorize()` work on the web? How do I handle login?
+
+This is a key difference between native and web platforms.
+
+- **On Native (iOS/Android):** `authorize()` opens an in-app browser overlay. Your app continues running in the background. When the user authenticates, the browser dismisses and the `authorize()` promise resolves with the credentials. `await` works as expected.
+
+- **On Web:** `authorize()` triggers a **full-page browser redirect** to the Auth0 Universal Login page. Your application's current state is lost. After authentication, the user is redirected back to your app, which causes your entire React application to reload and re-initialize from scratch. Because of this, the original `authorize()` promise is never able to resolve.
+
+**The Solution: Use the `useAuth0` Hook**
+
+The recommended way to handle this is by using the `Auth0Provider` and `useAuth0` hook. They are designed to manage this flow automatically:
+
+1.  **On initial load:** The provider checks if the user is returning from a login redirect. If so, it processes the credentials in the URL and establishes a session.
+2.  **State Management:** The `user` and `isLoading` properties from the `useAuth0` hook will automatically update to reflect the authenticated state after the redirect is handled.
+
+Your UI should be reactive to the `user` and `isLoading` state, rather than trying to `await` the result of `authorize()`.
+
+```jsx
+import { useAuth0 } from 'react-native-auth0';
+
+const MyComponent = () => {
+  const { authorize, user, isLoading } = useAuth0();
+
+  // This component will re-render after the redirect,
+  // and `user` will be populated.
+  if (isLoading) {
+    return <Text>Loading...</Text>;
+  }
+
+  return (
+    <View>
+      {user ? (
+        <Text>Welcome, {user.name}!</Text>
+      ) : (
+        <Button
+          title="Log In"
+          onPress={async () => {
+            // This will trigger the redirect. No need to `await`.
+            await authorize();
+          }}
+        />
+      )}
+    </View>
+  );
+};
+```
+
+## 11. Why do my users get logged out frequently? How do I keep them logged in?
+
+If your users are being asked to log in again after a short period (e.g., when they close and reopen the app), it's likely because the SDK cannot silently refresh their tokens.
+
+The `getCredentials()` method is responsible for retrieving tokens. If the `accessToken` is expired, it will attempt to get a new one using a `refreshToken`. This process happens silently without requiring user interaction.
+
+To enable this, you **must** request the `offline_access` scope during the initial login. This scope is what signals to Auth0 that you want to receive a `refreshToken`.
+
+**The Solution: Add the `offline_access` Scope**
+
+When calling `authorize`, ensure you include `offline_access` in the scope string.
+
+```javascript
+import { useAuth0 } from 'react-native-auth0';
+
+const { authorize } = useAuth0();
+
+const handleLogin = async () => {
+  await authorize({
+    scope: 'openid profile email offline_access', // <-- Add this scope
+  });
+};
+```
+
+By including this scope, the SDK will receive and securely store a `refreshToken`. This token will then be used by `getCredentials()` to maintain the user's session across app launches, providing a much smoother user experience.

MIGRATION_GUIDE.md

@@ -73,36 +73,7 @@ To align with modern JavaScript standards, all properties on the `user` object a
 | `user.phone_number`   | `user.phoneNumber`   |
 | ...and so on.         |                      |
 
-### Change #2: Credentials Object uses `expiresAt`
-
-The `Credentials` object no longer includes `expiresIn` (a duration). It now provides `expiresAt`, an absolute **UNIX timestamp** (in seconds), making expiration checks simpler and less error-prone.
-
-**✅ Action Required:** Replace all logic using `expiresIn` with `expiresAt`.
-
-**Before:**
-
-```javascript
-const expiresAt = Date.now() / 1000 + credentials.expiresIn;
-if (isExpired(expiresAt)) {
-  // ...
-}
-```
-
-**After:**
-
-```javascript
-// Direct comparison is now possible
-if (credentials.expiresAt < Date.now() / 1000) {
-  // ...
-}
-
-// Or, use the new helper method (if you have an instance of the Credentials model):
-if (credentials.isExpired()) {
-  // ...
-}
-```
-
-### Change #3: Standardized `AuthError` Object
+### Change #2: Standardized `AuthError` Object
 
 All errors thrown by the library are now instances of a single, consistent `AuthError` class. This replaces multiple error types like `CredentialsManagerError`.
 
@@ -130,32 +101,73 @@ catch (e) {
 }
 ```
 
-### Change #4: Updated `authorize` and `clearSession` Signatures
+### Change #3: Platform-Specific API Availability
+
+With the introduction of **React Native Web support**, some methods are only available on native platforms for security reasons. Direct authentication grants that handle user credentials (like passwords or OTP codes) are **not supported in the browser** and will throw a `NotImplemented` error.
+
+**✅ Action Required:** If you are building for the web, ensure all authentication flows are initiated via the redirect-based `authorize()` method. Review the platform support table in the [README](README.md#features-and-platform-support) for a full list of platform-specific methods.
+
+### Change #4: `authorize()` Behavior on Web
 
-For improved clarity, SDK-specific options (like `ephemeralSession`) have been moved into a separate, second `options` object.
+On React Native Web, the `authorize()` method now triggers a **full-page redirect** to Auth0. As a result, the promise returned by `authorize()` will **not resolve** in the browser. Your application must be structured to handle the user state upon reloading after the redirect.
 
-**✅ Action Required:** Restructure calls to `authorize` and `clearSession`.
+**✅ Action Required:** Review the new **[FAQ entry](#faq-authorize-web)** for guidance on how to correctly handle the post-login flow on the web. The `Auth0Provider` and `useAuth0` hook are designed to manage this flow automatically.
+
+### Change #5: New Peer Dependency for Web Support
+
+To support the web platform, the library now has an **optional peer dependency** on `@auth0/auth0-spa-js`.
+
+**✅ Action Required:** If you are using `react-native-auth0` in a React Native Web project, you **must** install this package. Native-only projects can ignore this.
+
+```bash
+npm install @auth0/auth0-spa-js
+```
+
+### Change #6: Hook Methods Now Throw Error
+
+Previously, all hook-related methods such as `getCredentials()`, `saveCredentials()`, etc., did not throw error directly. Instead, any issues were silently handled and surfaced via the error property in `useAuth0()`:
+
+```javascript
+const { error } = useAuth0();
+// error would be populated if getCredentials failed
+```
+
+**What's Changed:**
+
+These methods now throw error directly to the caller. You must handle them explicitly using try...catch blocks.
+
+**✅ Action Required:** Update your code to handle error for each function call individually.
 
 **Before:**
 
 ```javascript
-// Mixed parameters and options
-await authorize({
-  scope: 'openid profile',
-  ephemeralSession: true,
-});
+const { getCredentials, error } = useAuth0();
+---
+await getCredentials();
+// Check error manually later
 ```
 
 **After:**
 
 ```javascript
-// Parameters and options are now separate arguments
-await authorize(
-  { scope: 'openid profile' }, // 1. OIDC / Auth0 Parameters
-  { ephemeralSession: true } // 2. SDK-Specific Options
-);
+const { getCredentials, error } = useAuth0();
+
+try {
+  await getCredentials();
+} catch (e) {
+  console.error(e);
+}
 ```
 
+All thrown errors are instances of the new standardized AuthError class described in Change #2.
+
+### Recommended Reading
+
+After migrating, we highly recommend reviewing the updated **[FAQ](FAQ.md)** for detailed explanations on:
+
+- How to handle the `authorize()` redirect flow on the web.
+- The importance of the `offline_access` scope for keeping users logged in.
+
 ## Upgrading from v3 -> v4
 
 - **If your project is built with Expo:**

REACT_NATIVE_WEB_SETUP.md

@@ -0,0 +1,62 @@
+# React Native Web Configuration Guide
+
+This guide provides instructions for using React Native Auth0 with React Native Web.
+
+## What is React Native Web?
+
+React Native Web is a library that provides React Native components and APIs that are compatible with React and the web. It allows you to write your application once using React Native and run it on iOS, Android, and web platforms.
+
+**Official React Native Web Repository:** https://github.com/necolas/react-native-web
+
+## Setup Instructions
+
+If you want to use React Native Web with React Native Auth0, follow these steps:
+
+### 1. Install React Native Web
+
+Follow the official React Native Web installation guide:
+**https://necolas.github.io/react-native-web/docs/setup/**
+
+### 2. Install Auth0 SPA JS (Required for Web)
+
+React Native Auth0 requires `@auth0/auth0-spa-js` for web platform support:
+
+```bash
+# Using npm
+npm install @auth0/auth0-spa-js
+
+# Using yarn
+yarn add @auth0/auth0-spa-js
+```
+
+### 3. Use React Native Auth0
+
+Once React Native Web and Auth0 SPA JS are installed, you can use React Native Auth0 exactly as you would in a native React Native app. The library will automatically detect the web platform and use the appropriate implementation.
+
+## Example Usage
+
+```jsx
+import React from 'react';
+import { Auth0Provider } from 'react-native-auth0';
+
+const App = () => (
+  <Auth0Provider domain="YOUR_AUTH0_DOMAIN" clientId="YOUR_AUTH0_CLIENT_ID">
+    {/* Your app components */}
+  </Auth0Provider>
+);
+
+export default App;
+```
+
+## Resources
+
+- **React Native Web Setup Guide**: https://necolas.github.io/react-native-web/docs/setup/
+- **React Native Web GitHub**: https://github.com/necolas/react-native-web
+- **Auth0 SPA JS**: https://github.com/auth0/auth0-spa-js
+- **React Native Auth0 Documentation**: https://auth0.github.io/react-native-auth0/
+
+## Notes
+
+- React Native Auth0 automatically detects when running on web and uses the Auth0 SPA JS library under the hood
+- All React Native Auth0 APIs work the same across platforms (iOS, Android, and Web)
+- For web-specific examples, see the [EXAMPLES-WEB.md](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES-WEB.md) file in this repository

README.md

@@ -23,8 +23,10 @@ We're excited to announce the release of react-native-auth0 `v4.0.0` and the bet
 - [Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive)
 - [Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Hooks)
 - [Expo Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo)
+- [React Native Web Setup](https://github.com/auth0/react-native-auth0/blob/master/REACT_NATIVE_WEB_SETUP.md)
 - [FAQs](https://github.com/auth0/react-native-auth0/blob/master/FAQ.md)
 - [Examples](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md)
+- [Examples for Web](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES-WEB.md)
 - [Docs Site](https://auth0.github.io/react-native-auth0/)
 
 ## Getting Started

docs/.nojekyll

@@ -29,6 +29,8 @@
   --dark-hl-13: #d4d4d4;
   --light-hl-14: #0070c1;
   --dark-hl-14: #4fc1ff;
+  --light-hl-15: #098658;
+  --dark-hl-15: #b5cea8;
   --light-code-background: #ffffff;
   --dark-code-background: #1e1e1e;
 }
@@ -50,6 +52,7 @@
     --hl-12: var(--light-hl-12);
     --hl-13: var(--light-hl-13);
     --hl-14: var(--light-hl-14);
+    --hl-15: var(--light-hl-15);
     --code-background: var(--light-code-background);
   }
 }
@@ -71,6 +74,7 @@
     --hl-12: var(--dark-hl-12);
     --hl-13: var(--dark-hl-13);
     --hl-14: var(--dark-hl-14);
+    --hl-15: var(--dark-hl-15);
     --code-background: var(--dark-code-background);
   }
 }
@@ -91,6 +95,7 @@
   --hl-12: var(--light-hl-12);
   --hl-13: var(--light-hl-13);
   --hl-14: var(--light-hl-14);
+  --hl-15: var(--light-hl-15);
   --code-background: var(--light-code-background);
 }
 
@@ -110,6 +115,7 @@
   --hl-12: var(--dark-hl-12);
   --hl-13: var(--dark-hl-13);
   --hl-14: var(--dark-hl-14);
+  --hl-15: var(--dark-hl-15);
   --code-background: var(--dark-code-background);
 }
 
@@ -158,6 +164,9 @@
 .hl-14 {
   color: var(--hl-14);
 }
+.hl-15 {
+  color: var(--hl-15);
+}
 pre,
 code {
   background: var(--code-background);