Skip to content

Conversation

subhankarmaiti
Copy link
Contributor

@subhankarmaiti subhankarmaiti commented Jul 11, 2025

Summary & Motivation

This pull request introduces a major architectural refactor of the react-native-auth0 library. The primary goal is to evolve from the existing tightly-coupled implementation to a highly abstracted, modular, and extensible architecture that cleanly supports multiple platforms (Native and Web) in a maintainable way.

The previous structure made it difficult to add new features or platforms without significant code duplication and risk of regressions. This new architecture establishes a clear separation of concerns, making the library more robust, performant, and easier for future contributors to understand and extend.

The New Architecture

The new design is built on the Dependency Inversion Principle, using a Factory pattern to provide the correct platform-specific implementation at build time. High-level modules (like the React hooks) are now completely decoupled from low-level platform details (the native bridge or auth0-spa-js).

High-Level Diagram

This diagram illustrates the new flow of control. The key concept is that the consumer-facing API is decoupled from the platform implementations via a Factory that chooses the correct module at build time.

graph TD
    subgraph " "
        direction LR
        A["React Hooks / Developer"]
    end
    
    A --> B[Auth0 Facade Class];
    B --> C{Auth0ClientFactory};
    
    subgraph " "
        direction LR
        C -- instantiates --> D["IAuth0Client (The Contract)"];
    end
    
    subgraph "Platform Implementations"
        direction LR
        subgraph " "
            E[NativeAuth0Client] --> D;
        end
        subgraph " "
            F[WebAuth0Client] --> D;
        end
    end

    subgraph " "
        direction LR
        E -- uses --> G[Native Bridge & Adapters];
    end
    
    subgraph " "
        direction LR
        F -- uses --> H[auth0-spa-js & Adapters];
    end

    G --> I[iOS / Android];
    H --> J[Browser];

    style A fill:#cde4ff,stroke:#6a9fde,stroke-width:2px
    style B fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    style C fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    style D fill:#fff2cc,stroke:#d6b656,stroke-width:2px
Loading

Key Architectural Components

  1. src/core: The platform-agnostic heart of the library.

    • interfaces: Defines the "contract" for what our client can do (IAuth0Client, IWebAuthProvider, etc.). This is the cornerstone of the abstraction.
    • models: Concrete data models like Auth0User and Credentials that encapsulate data and related logic (e.g., isExpired()).
    • services: "Orchestrator" classes that contain the business logic for authentication flows (e.g., CredentialsOrchestrator handles the token refresh flow).
  2. src/platforms: Contains the platform-specific implementations.

    • native: The complete module for iOS and Android, containing the NativeBridgeManager for low-level communication and a set of adapters that implement the core interfaces.
    • web: The complete module for React Native Web, containing a set of adapters that wrap the @auth0/auth0-spa-js library to make it conform to our core interfaces.
  3. src/factory: The "decision-making" layer that runs at build time.

    • Uses platform-specific file extensions (.ts, .web.ts) to ensure the bundler (Metro/Webpack) includes only the code for the target platform. This completely severs the dependency on @auth0/auth0-spa-js in native builds.
  4. src/hooks & src/index.ts (Public API):

    • The Auth0 class now acts as a simple Facade, which uses the factory to get the correct client. This maintains backward compatibility.
    • The Auth0Provider uses this facade to power the useAuth0 hook, providing a seamless and performant stateful experience. Issues with UI hanging on logout and infinite re-renders have been fixed.

Key Breaking Changes for Users

A full MIGRATION_GUIDE.md has been created, but the most critical changes are:

  1. camelCase Properties: Properties on the user object are now camelCase (e.g., user.givenName instead of user.given_name).
  2. expiresAt Timestamp: The Credentials object now provides a expiresAt UNIX timestamp instead of expiresIn.
  3. Unified AuthError: All errors are now instances of a single, consistent AuthError class.
  4. Separated Method Arguments: Methods like authorize now separate OIDC parameters and SDK options into two distinct arguments: authorize({scope}, {options}).

Testing Strategy

A comprehensive, co-located test suite has been implemented for the new architecture.

  • All legacy test cases have been migrated to validate the new components, ensuring full functional parity.
  • The testing setup now uses a global __mocks__ directory for react-native, creating a clean and stable test environment.
  • The new structure is significantly more unit-testable, allowing for isolated testing of core services, adapters, and utilities.

How to Review This PR

Given the scope of the refactor, a commit-by-commit review is highly recommended. The commits have been structured logically to tell the story of the new architecture's construction:

  1. feat(core): Introduce foundational types and interfaces...: Establishes the core contracts.
  2. feat(core): Implement core data models and utility functions...: Adds the reusable building blocks.
  3. feat(core): Implement platform-agnostic service orchestrators...: Introduces the platform-agnostic business logic.
  4. feat(factory): Implement platform detector and client factory...: Builds the platform-selection mechanism.
  5. feat(platform): Implement native platform...: Adds the complete native implementation.
  6. feat(platform): Implement web platform...: Adds the complete web implementation.
  7. feat(hooks): Implement public Auth0 facade and update hooks...: Wires everything up to the consumer-facing API.
  8. test: Implement comprehensive test suite...: Adds all the new tests.

guabu and others added 30 commits April 2, 2025 12:39
@subhankarmaiti subhankarmaiti marked this pull request as ready for review July 14, 2025 03:55
@subhankarmaiti subhankarmaiti requested a review from a team as a code owner July 14, 2025 03:55
…hProvider to use Auth0Client directly and add unit tests for WebWebAuthProvider
…hProvider to use Auth0Client directly and add unit tests for WebWebAuthProvider
…examples, update documentation, and add redirect handling
- Updated ClassApp to handle errors without logging the error object.
- Enhanced Auth0Provider tests to simulate loading states and credential retrieval.
- Implemented unimplemented methods in NativeWebAuthProvider to throw AuthError.
- Refactored WebAuth0Client to use a singleton pattern for Auth0Client instance.
- Improved WebWebAuthProvider to handle redirect callbacks and errors more gracefully.
- Added comprehensive tests for WebAuth0Client and WebCredentialsManager to ensure correct behavior.
- Created tests for UnimplementedWebAuthenticationProvider to validate error handling.
- Added tests for WebCredentialsManager to verify credential management functionality.
@subhankarmaiti subhankarmaiti merged commit ecf0577 into master Jul 21, 2025
4 checks passed
@subhankarmaiti subhankarmaiti deleted the refactor_v5 branch July 21, 2025 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants