@truworth/twc-auth

Truworth Auth Module - A comprehensive authentication solution for React Native and Web applications.

Table of Contents

• Installation
  • Mobile ( React Native )
  • Web ( Next.js )
• Development
  • Mobile ( React Native Setup for Hot Reloading )
  • Web ( Next.js Setup for Hot Reloading )
• Usage
• API Reference
• Troubleshooting

Installation

React Native

1. Install the package:

   npm install @truworth/twc-auth

2. Install peer dependencies:

   npm install \
     @react-native-community/datetimepicker \
     @react-navigation/native \
     @react-navigation/native-stack \
     @truworth/twc-rn-common \
     @eva-design/eva \
     @ui-kitten/components \
     react-native-gesture-handler \
     react-native-linear-gradient \
     react-native-modalize \
     react-native-reanimated \
     react-native-screens \
     react-native-safe-area-context \
     react-native-svg \
     react-native-vector-icons \
     react@^18.2.0 \
     react-native@^0.74.5

3. For iOS, install pods:

   npx pod-install

4. For React Native Reanimated, follow the installation steps if you haven't already.

5. For React Navigation, wrap your app with NavigationContainer and ensure you've followed the getting started guide.

React Native Dependencies

| Package | Version | | -------------------------------------- | -------- | | @react-native-community/datetimepicker | >=8.1.1 | | @react-navigation/native | >=6.1.17 | | @react-navigation/native-stack | >=6.10.0 | | @truworth/twc-rn-common | >=1.0.12 | | @ui-kitten/components | >=5.1.2 | | @eva-design/eva | >=2.2.0 | | lottie-react-native | >=6.7.2 | | react | >=18.2.0 | | react-native | >=0.74.5 | | react-native-fast-image | >=8.6.3 | | react-native-gesture-handler | >=2.16.0 | | react-native-linear-gradient | >=2.8.3 | | react-native-modalize | >=2.1.1 | | react-native-reanimated | >=3.13.0 | | react-native-safe-area-context | >=5.3.0 | | react-native-screens | >=3.31.1 | | react-native-svg | >=15.8.0 | | react-native-vector-icons | >=9.2.0 |

Note: lottie-react-native, react-native-fast-image are optional and only needed if your app uses features that depend on them.

Web Dependencies

| Package | Version | | ------------------------ | -------- | | @react-google-maps/api | >=2.20.6 | | @truworth/twc-web-design | >=1.9.0 | | antd | >=5.6.3 | | framer-motion | >=12.6.2 | | lodash | >=4.17.21 | | lucide-react | >=0.483.0 | | next | ^15.0.4 | | react | >=18.2.0 | | react-dom | >=18.2.0 |

Web

1. Install the package:

   npm install @truworth/twc-auth

2. Install peer dependencies:

   npm install \
     next@^15.0.4 \
     @react-google-maps/api@>=2.20.6 \
     @truworth/twc-web-design@>=1.9.0 \
     antd@>=5.6.3 \
     framer-motion@>=12.6.2 \
     lodash@>=4.17.21 \
     lucide-react@>=0.483.0 \
     react@>=18.2.0 \
     react-dom@>=18.2.0

Running the Example Applications of the TWC-Auth Package

This repository includes example applications for both mobile (React Native) and web (Next.js).

Running the Mobile App

1. Navigate to the mobile app directory:

   cd apps/mobile

2. Install dependencies:

   npm install

3. Run on Android:

   npm run android

4. Run on iOS:

   First, install the pods and build the application:

   cd ios && pod install && cd ..
   npm run build:ios

   Then, run the application:

   npm run ios

Running the Web App

1. Navigate to the web app directory:

   cd apps/web

2. Create a .env file:

   Copy the example environment variables below into a new file named .env in the apps/web directory.

   NEXT_PUBLIC_ENVIRONMENT=development/production
   
   NODE_ENV=development/production
   
   NEXT_PUBLIC_MEMBER_IMAGES_URL=<value>
   
   NEXT_PUBLIC_TWC_API_BASE_URL=<value>
   
   NEXT_PUBLIC_CDN_IMAGES_URL=<value>
   
   NEXT_PUBLIC_GTM_ID=<value>
   
   NEXT_PUBLIC_RECAPTCHA_SITE_KEY=<value>

3. Install dependencies:

   npm install

4. Run the development server:

   npm run dev

   Open http://localhost:3000 with your browser to see the result.

Development: Configure Hot Reloading

React Native Setup for Hot Reloading

Prerequisites

Update main field in package.json to ./src/index.tsx

//package.json
{
  ...
- "main": "./build/src/index.js"
+ "main": "./src/index.tsx"
  ...
}

Note: This change is for local development (hot reloading) only. Before publishing, restore "main" to the built JS (e.g., ./build/src/index.js) or use the "exports" field to map dev vs prod entry points.

Add package to your main project's package.json file's dependencies field

//package.json
{
  ...
  "dependencies": {
    ...
+    "@truworth/twc-auth": "file:relative/path/to/package"
    ...
  }
  ...
}

React Native

Copy get-metro-config.js in your main project

Import getMetroConfig from get-metro-config.js and use it to merge with your project's metro config

// mainProject/metro.config.js
+ const { getMetroConfig } = require('./get-metro-config')
+ const packageConfig = getMetroConfig(__dirname, 'relative/path/to/package')
...
- module.exports = mergeConfig(defaultConfig, config);
+ module.exports = mergeConfig(defaultConfig, config, packageConfig);

Next.js Setup for Hot Reloading

Copy get-next-config.js in your main project

Import getNextConfig from get-next-config.js and use it to merge with your project's next config

// mainProject/next.config.js
+ const { getNextConfig } = require('./get-next-config')
+ const packageConfig = getNextConfig(__dirname, 'relative/path/to/package')
...
const nextConfig = {
...
+ transpilePackages: [packageConfig.packageName],
  webpack: (config) => {
    ...
+   config.resolve.alias = {
+   ...config.resolve.alias,
+   ...packageConfig.webpackAlias
+   }
    ...
    return config;
  },
}
...
module.exports = nextConfig;

Note on CSS Imports: When hot reloading the @truworth/twc-web-design package locally, you need to import the CSS from the dist folder in your _app.tsx file:

import "@truworth/twc-web-design/dist/main.css";

When using the published version of the package, import the styles directly:

import "@truworth/twc-web-design/style.css";

Usage

Below are examples of how to integrate and use the AuthProvider in your application.

React Native

import React from "react";
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import { NavigationContainer } from "@react-navigation/native";
import { AuthNavigator, AuthProvider } from "@truworth/twc-auth";
import type { LoginResponse } from "@truworth/twc-auth";
import { Image, Text } from 'react-native';

const { Navigator, Screen } = createNativeStackNavigator();

// A custom component to display your brand's logo on the auth screens.
const CustomLogo = () => <Image source={require('./path/to/your/logo.png')} style={{ width: 100, height: 50 }} />;

const ExampleAppNavigator = () => {

  // Callback for when the user successfully logs in.
  const onLogin = (result: LoginResponse) => {
    console.log("Login successful:", result.token);
    // TODO: Store token in secure storage & navigate to the main app screen.
  };

  // Callback for when the user logs out.
  const onLogout = () => {
    console.log("User logged out");
    // TODO: Clear token from storage & navigate to the login screen.
  };

  // Configuration for your app's branding and support details.
  const appConfig = {
    appName: 'Your App Name',
    supportEmail: '[email protected]',
    privacyPolicyUrl: 'https://yourapp.com/privacy',
    termsAndConditionsUrl: 'https://yourapp.com/terms'
  };

  return (
    <NavigationContainer>
      <AuthProvider
        onLogin={onLogin}
        onLogout={onLogout}
        appConfig={appConfig}
        LogoComponent={CustomLogo}
      >
        <Navigator screenOptions={{ headerShown: false }}>
          <Screen name="AuthNavigator" component={AuthNavigator} />
          {/* Add your main app screens here after the auth flow */}
        </Navigator>
      </AuthProvider>
    </NavigationContainer>
  );
};

export default ExampleAppNavigator;

Web (Next.js)

// pages/_app.tsx
import { AuthProvider } from "@truworth/twc-auth";
import type { LoginResponse } from "@truworth/twc-auth";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {

  // Callback for when the user successfully logs in.
  const onLogin = (result: LoginResponse) => {
    console.log("Login successful:", result.token);
    // TODO: Store token (e.g., in an HTTP-only cookie) & redirect.
  };

  // Callback for when the user logs out.
  const onLogout = () => {
    console.log("User logged out");
    // TODO: Clear token and redirect to the login page.
  };

  // Configuration for your app's branding and support details.
  const appConfig = {
    appName: 'Your Web App',
    supportEmail: '[email protected]',
    privacyPolicyUrl: 'https://yourwebapp.com/privacy',
    termsAndConditionsUrl: 'https://yourwebapp.com/terms'
  };

  return (
    <AuthProvider
      onLogin={onLogin}
      onLogout={onLogout}
      appConfig={appConfig}
    >
      <Component {...pageProps} />
    </AuthProvider>
  );
}

API Reference

Hooks

useAuthContext()

const {
  token,
  profile,
  client,
  isLoadingProfile,
  logout,
  onLaunchAuthSession,
  getUserProfile,
  onOtpReceived,
} = useAuthContext();

Components

<AuthProvider>

The AuthProvider component provides authentication state and actions to its children. It should wrap the root of your application or the part of your app that requires authentication.

Props

| Prop | Type | Description | | --------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | React children to be rendered inside the provider. | | LogoComponent | React.ComponentType | Optional component for branding/logo in auth flows. | | session | { token: string } | Initial session containing the auth token. | | appConfig | AppConfig | Optional app configuration for auth flows (appName, supportEmail, privacyPolicyUrl, termsAndConditionsUrl). | | onLogin | (result: LoginResponse) => void | Optional callback after a successful login. | | onLogout | () => void | Optional callback after a successful logout. | | onLaunchAuthSession | () => void | Optional callback after successfully launching the auth session. Can be used to set a Firebase notification token or request Android permissions, for example. | | onRefreshSession | (session: { token: string }) => void | Optional handler for refreshing the user session. | | openChatSupport | () => void | Optional callback to open chat support. | | socialLoginConfig | SocialLoginConfig | Optional social login configuration. |

Troubleshooting

Common Issues

1. Module not found

   • Ensure all peer dependencies are installed
   • Clear Metro bundler cache: npx react-native start --reset-cache
   • For Next.js, remove .next and restart: rm -rf .next && next dev
   • For React Native: Ensure babel.config.js includes plugins: ['react-native-reanimated/plugin'] as the last plugin
   • For Next.js with Babel: Add plugins: ['react-native-reanimated/plugin'] to your Babel config if using Babel (not needed with default SWC)
   • For iOS CocoaPods issues: First try cd ios && pod install or clean the build folder in Xcode. Only use pod deintegrate as a last resort if other steps fail.