naim-firebase-auth-wrapper/README.md

React components and hooks for Firebase Authentication and Firestore with Mantine UI

# Firebase Auth Wrapper

A lightweight React component library for Firebase Authentication and Firestore that simplifies user management, authentication, and organization handling.

[![npm version](https://img.shields.io/npm/v/naim-firebase-auth-wrapper.svg)](https://www.npmjs.com/package/naim-firebase-auth-wrapper)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What This Package Does

This package provides ready-to-use React components and hooks that handle:

- **Authentication**: Login, registration, password reset, and Google sign-in
- **User Management**: Profile creation, updates, and session management
- **Organization Management**: Create and manage multi-tenant organizations
- **Role-Based Access**: Control user permissions within organizations
- **Invitations**: Invite users to organizations with customizable roles

All components are built with [Mantine UI](https://mantine.dev/) for a modern, responsive design.

## Installation

```bash
npm install naim-firebase-auth-wrapper
# or
yarn add naim-firebase-auth-wrapper
```

## Quick Start

### 1. Wrap your app with AuthProvider

```jsx
// _app.jsx or App.jsx
import { AuthProvider } from 'naim-firebase-auth-wrapper';
import 'naim-firebase-auth-wrapper/style.css';

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  // ... other Firebase config
};

function MyApp({ Component, pageProps }) {
  return (
    <AuthProvider config={firebaseConfig}>
      <Component {...pageProps} />
    </AuthProvider>
  );
}

export default MyApp;
```

### 2. Use authentication components

```jsx
import { Login, Register, Logout } from 'naim-firebase-auth-wrapper';

// Login component
function LoginPage() {
  return (
    <Login 
      onSuccess={() => console.log('Login successful')}
      onError={(error) => console.error('Login failed:', error)}
      onRegisterClick={() => navigate('/register')}
    />
  );
}

// Register component
function RegisterPage() {
  return (
    <Register 
      onSuccess={() => console.log('Registration successful')}
      onError={(error) => console.error('Registration failed:', error)}
      onLoginClick={() => navigate('/login')}
    />
  );
}

// Logout button
function LogoutButton() {
  return (
    <Logout 
      onSuccess={() => console.log('Logout successful')}
      onError={(error) => console.error('Logout failed:', error)}
    />
  );
}
```

### 3. Access authentication state with useAuth hook

```jsx
import { useAuth } from 'naim-firebase-auth-wrapper';

function ProfilePage() {
  const { user, loading, error } = useAuth();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return <div>Please log in</div>;

  return (
    <div>
      <h1>Welcome, {user.displayName || user.email}</h1>
      <p>Email: {user.email}</p>
    </div>
  );
}
```

### 4. Manage user profiles

```jsx
import { UserProfile } from 'naim-firebase-auth-wrapper';

function ProfilePage() {
  return (
    <UserProfile 
      onSuccess={() => console.log('Profile updated')}
      onError={(error) => console.error('Profile update failed:', error)}
    />
  );
}
```

### 5. Manage organizations

```jsx
import { 
  OrganizationManagement, 
  CreateOrganization 
} from 'naim-firebase-auth-wrapper';

function OrganizationsPage() {
  return (
    <div>
      <h1>Your Organizations</h1>
      <OrganizationManagement 
        onError={(error) => console.error('Organization error:', error)}
      />
      
      <h2>Create New Organization</h2>
      <CreateOrganization 
        onSuccess={(orgId) => console.log('Organization created:', orgId)}
        onError={(error) => console.error('Organization creation failed:', error)}
      />
    </div>
  );
}
```

## Next.js Integration

When using with Next.js, make sure to:

1. Add the `'use client'` directive to components using this library
2. Add the package to `transpilePackages` in your `next.config.js`:

```js
// next.config.js
module.exports = {
  transpilePackages: ['naim-firebase-auth-wrapper']
}
```

## Available Components

- `AuthProvider` - Context provider for authentication state
- `Login` - Email/password and Google sign-in form
- `Register` - User registration form
- `Logout` - Logout button
- `UserProfile` - User profile management form
- `PasswordChange` - Password change form
- `OrganizationManagement` - Organization management dashboard
- `CreateOrganization` - Organization creation form
- `OrganizationSelector` - Dropdown to select current organization
- `SessionManager` - User session management
- `InviteUserForm` - Form to invite users to an organization
- `InvitationList` - List of pending invitations
- `AcceptInvitation` - Component to accept/decline invitations

## API Reference

For detailed API documentation, see the [API Reference](DOCUMENTATION.md).

## Example Application

Check out the included Next.js example application that demonstrates all features:

```bash
# Clone the repository
git clone https://github.com/NaimSakaamini/user-management.git

# Install dependencies
cd user-management
npm install

# Run the example app
npm run example:setup
```

## License

MIT © [Naim Sakaamini](https://github.com/NaimSakaamini)