diff --git a/packages/google-signin/README.md b/packages/google-signin/README.md new file mode 100644 index 0000000..1b61e32 --- /dev/null +++ b/packages/google-signin/README.md @@ -0,0 +1,358 @@ +# React Auth - Google Sign-In + +> Google Sign-In adapter for [@forward-software/react-auth](https://github.com/forwardsoftware/react-auth) - Web and React Native + +Self-contained Google Sign-In integration with no external auth wrapper dependencies. Provides a ready-made `AuthClient` implementation and a drop-in `GoogleSignInButton` for both platforms. + +--- + +## Install + +```sh +npm install @forward-software/react-auth @forward-software/react-auth-google +``` + +### Platform requirements + +**Web** - No additional dependencies. The package loads the Google Identity Services (GSI) script automatically (with a 10-second timeout). + +**React Native / Expo** - Requires a development build (not compatible with Expo Go): + +- iOS: Add the `GoogleSignIn` CocoaPod (included automatically via autolinking) +- Android: Uses Android Credential Manager with Google Identity (included via `build.gradle`) +- Run `npx expo prebuild` or use EAS Build to compile native code + +--- + +## Quick Start + +### 1. Create the auth client + +The setup is identical on both platforms - the bundler automatically resolves the correct implementation. + +```ts +// auth.ts +import { createAuth } from '@forward-software/react-auth'; +import { GoogleAuthClient } from '@forward-software/react-auth-google'; + +const googleAuth = new GoogleAuthClient({ + clientId: 'YOUR_GOOGLE_CLIENT_ID', +}); + +export const { AuthProvider, authClient, useAuthClient } = createAuth(googleAuth); +``` + +### 2. Wrap your app with AuthProvider + +```tsx +// App.tsx +import { AuthProvider } from './auth'; + +function App() { + return ( + + + + ); +} +``` + +### 3. Add the sign-in button + +```tsx +import { GoogleSignInButton } from '@forward-software/react-auth-google'; +import { useAuthClient } from './auth'; + +function LoginScreen() { + const authClient = useAuthClient(); + + return ( + authClient.login(credentials)} + onError={(err) => console.error(err)} + /> + ); +} +``` + +That's it - the button handles the full Google Sign-In flow and the auth client manages tokens, persistence, and state. + +--- + +## Web Setup + +### Configuration + +```ts +import { GoogleAuthClient } from '@forward-software/react-auth-google'; + +const googleAuth = new GoogleAuthClient({ + clientId: 'YOUR_GOOGLE_CLIENT_ID', + + // Optional + scopes: ['openid', 'profile', 'email'], // default + persistTokens: true, // default - stores tokens in localStorage + storageKey: '@react-auth/google-tokens', // default + ux_mode: 'popup', // 'popup' | 'redirect' + redirect_uri: undefined, // required if ux_mode is 'redirect' + hosted_domain: undefined, // restrict to a G Suite domain + nonce: undefined, // binds the ID token to a session (replay attack prevention) +}); +``` + +### Custom storage + +By default, the web adapter uses `localStorage`. You can provide a custom storage: + +```ts +const googleAuth = new GoogleAuthClient({ + clientId: 'YOUR_GOOGLE_CLIENT_ID', + storage: { + getItem: (key) => sessionStorage.getItem(key), + setItem: (key, value) => sessionStorage.setItem(key, value), + removeItem: (key) => sessionStorage.removeItem(key), + }, +}); +``` + +### GoogleSignInButton (Web) + +Renders Google's official branded sign-in button via the GSI script. + +```tsx + authClient.login(credentials)} + onError={(err) => console.error(err)} + + // Optional - Google button customization + theme="outline" // 'outline' | 'filled_blue' | 'filled_black' + size="large" // 'large' | 'medium' | 'small' + text="signin_with" // 'signin_with' | 'signup_with' | 'continue_with' | 'signin' + shape="rectangular" // 'rectangular' | 'pill' | 'circle' | 'square' + width={300} +/> +``` + +### Manual integration (without GoogleSignInButton) + +If you prefer full control over the UI, use the GSI utilities directly: + +```tsx +import { useEffect, useRef } from 'react'; +import { loadGsiScript, initializeGsi, renderGsiButton } from '@forward-software/react-auth-google/web/gsi'; +import { useAuthClient } from './auth'; + +function CustomLogin() { + const authClient = useAuthClient(); + const buttonRef = useRef(null); + + useEffect(() => { + async function setup() { + await loadGsiScript(); + initializeGsi({ + client_id: 'YOUR_GOOGLE_CLIENT_ID', + callback: (response) => { + authClient.login({ idToken: response.credential }); + }, + }); + if (buttonRef.current) { + renderGsiButton(buttonRef.current, { theme: 'outline', size: 'large' }); + } + } + setup(); + }, []); + + return
; +} +``` + +### Token refresh on web + +Google Identity Services on the web does **not** provide refresh tokens. When the ID token expires, the user must sign in again. The adapter handles this automatically - `onInit()` returns `null` when stored tokens are expired, which transitions the auth state to unauthenticated. + +--- + +## React Native / Expo Setup + +### Configuration + +```ts +import { GoogleAuthClient } from '@forward-software/react-auth-google'; +import { MMKV } from 'react-native-mmkv'; + +const mmkv = new MMKV(); + +const googleAuth = new GoogleAuthClient({ + clientId: 'YOUR_GOOGLE_CLIENT_ID', + webClientId: 'YOUR_WEB_CLIENT_ID', // required for ID token retrieval on Android + iosClientId: 'YOUR_IOS_CLIENT_ID', // iOS-specific client ID (if different) + + // Required on React Native - no default storage + storage: { + getItem: (key) => mmkv.getString(key) ?? null, + setItem: (key, value) => mmkv.set(key, value), + removeItem: (key) => mmkv.delete(key), + }, + + // Optional + scopes: ['openid', 'profile', 'email'], + persistTokens: true, + storageKey: '@react-auth/google-tokens', + offlineAccess: false, +}); +``` + +> **Note:** On React Native, `storage` is a **required** field in the TypeScript type. Your project will not compile without providing a `TokenStorage` implementation. Use [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) (recommended) or wrap AsyncStorage with the `TokenStorage` interface. +> +> **Android scopes:** Android Credential Manager does not support OAuth scopes directly. If you request scopes beyond `openid`, `profile`, and `email`, the adapter will include a `serverAuthCode` in the response. Exchange this code on your backend for scoped access tokens via the Google OAuth2 token endpoint. + +### GoogleSignInButton (React Native) + +Renders a styled button that triggers the native Google Sign-In flow. + +```tsx + authClient.login(credentials)} + onError={(err) => Alert.alert('Error', err.message)} + style={{ marginTop: 20 }} + disabled={false} +/> +``` + +### Manual integration (without GoogleSignInButton) + +```tsx +import { GoogleSignInModule } from '@forward-software/react-auth-google'; +import { useAuthClient } from './auth'; + +function LoginScreen() { + const authClient = useAuthClient(); + + const handleSignIn = async () => { + try { + const credentials = await GoogleSignInModule.signIn(); + await authClient.login(credentials); + } catch (err) { + console.error(err); + } + }; + + return