ktp-login-react

A comprehensive React authentication library powered by Firebase. Provides pre-built components and hooks for implementing login flows with multiple OAuth providers and email/password authentication. Ships as an ESM library with TypeScript declarations.

Designed to work with the ktp-gcp-auth backend library from the ktor-plus project.

Features

• Firebase Authentication integration
• Multiple OAuth providers (Google, GitHub, Microsoft, Facebook)
• Email/password authentication with signup and password reset
• Pre-built, styled UI components
• Protected route component for securing pages
• Backend session synchronization
• Fully typed with TypeScript

Installation

npm install ktp-login-react

Peer Dependencies

This library requires the following peer dependencies:

npm install react react-dom firebase react-router-dom

Quick Start

1. Initialize the Library

Before using any components, initialize the library with your configuration:

// src/main.tsx or src/index.tsx
import { initializeAuthLibrary } from "ktp-login-react";

initializeAuthLibrary({
  firebase: {
    apiKey: "your-api-key",
    authDomain: "your-project.firebaseapp.com",
    projectId: "your-project-id",
  },
  auth: {
    enabledProviders: [
      "google.com",
      "github.com",
      "microsoft.com",
      "facebook.com",
      "password", // Email/password auth
    ],
    endpoints: {
      login: "/api/auth/login",
      logout: "/api/auth/logout",
    },
    routes: {
      login: "/login",
      signup: "/signup",
      resetPassword: "/reset-password",
      afterLogin: "/dashboard",
    },
    password: {
      minLength: 8,
    },
  },
});

2. Wrap Your App with AuthProvider

// src/App.tsx
import { AuthProvider } from "ktp-login-react";
import { BrowserRouter } from "react-router-dom";

function App() {
  return (
    <BrowserRouter>
      <AuthProvider>
        <YourRoutes />
      </AuthProvider>
    </BrowserRouter>
  );
}

3. Set Up Routes

You can easily add all authentication pages to your app using the AuthRoutes component. This will automatically register routes based on your configuration.

import { Routes, Route } from "react-router-dom";
import {
  AuthRoutes,
  ProtectedRoute,
  getAuthConfig,
} from "ktp-login-react";

function YourRoutes() {
  const { auth: { routes } } = getAuthConfig();

  return (
    <Routes>
      <Route path="/*" element={<AuthRoutes />} />

      {/* Protected routes */}
      <Route element={<ProtectedRoute />}>
        <Route path={routes.afterLogin} element={<Dashboard />} />
        <Route path="/profile" element={<Profile />} />
      </Route>
    </Routes>
  );
}

4. Use the Auth Hook

import { useAuth } from "ktp-login-react";

function Dashboard() {
  const { user, firebaseUser, isLoading, logout } = useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>Welcome, {user?.nameFirst}!</h1>
      <p>Email: {user?.email}</p>
      <button onClick={logout}>Log Out</button>
    </div>
  );
}

API Reference

Configuration

interface AuthLibraryConfig {
  firebase: FirebaseOptions; // Firebase configuration object

  auth: {
    enabledProviders: string[]; // Array of provider IDs to enable
    endpoints: {
      login: string; // Backend endpoint to sync Firebase auth
      logout: string; // Backend endpoint for logout
    };
    routes: {
      login: string; // Login page route
      signup: string; // Signup page route
      resetPassword: string; // Password reset page route
      afterLogin: string; // Redirect after successful login
    };
    password?: {
      minLength?: number; // Minimum password length (default: 6)
    };
  };
}

Provider IDs

Use these strings in the enabledProviders array:

• "google.com" - Google OAuth
• "github.com" - GitHub OAuth
• "microsoft.com" - Microsoft OAuth
• "facebook.com" - Facebook OAuth
• "password" - Email/password authentication

Exported Components

AuthProvider

Context provider that manages authentication state. Must wrap your app.

<AuthProvider>{children}</AuthProvider>

LoginPage

Pre-built login page with OAuth buttons and email/password form.

<LoginPage redirectTo="/custom-redirect" />

Props:

• redirectTo?: string - Override the default redirect after login

SignupPage

Pre-built signup page with email/password registration.

<SignupPage />

PasswordResetPage

Pre-built password reset request page.

<PasswordResetPage />

ProtectedRoute

Route guard that requires authentication. Renders LoginPage if not authenticated.

// As a layout route
<Route element={<ProtectedRoute />}>
  <Route path="/dashboard" element={<Dashboard />} />
</Route>

// With children
<ProtectedRoute>
  <Dashboard />
</ProtectedRoute>

Hooks

useAuth()

Returns the authentication context.

const { user, firebaseUser, isLoading, logout } = useAuth();

Returns:

• user: User | null - Backend user object
• firebaseUser: FirebaseUser | null - Firebase user object
• isLoading: boolean - Auth state loading indicator
• logout: () => Promise<void> - Logout function

Types

User

interface User {
  userId: string;
  email: string;
  nameFull: string;
  nameFirst: string;
  roles: string[];
  extra: unknown;
}

Firebase Utilities

Direct access to Firebase auth functions:

import {
  signInWithGoogle,
  signInWithGitHub,
  signInWithMicrosoft,
  signInWithFacebook,
  signInWithEmail,
  signUpWithEmail,
  resetPassword,
  signOutUser,
  subscribeToAuthState,
  MICROSOFT_PROVIDER_ID,
} from "ktp-login-react";

Backend Integration

This library is designed to work with the ktp-gcp-auth library from the ktor-plus project, which provides the required backend endpoints for Ktor applications.

The library expects your backend to have two endpoints:

POST /auth/login

Called after Firebase authentication to sync with your backend.

POST /auth/logout

Called when user logs out.

Local Development

To run the demo app locally and test the UI components:

1. Set up environment variables

Copy the example file and add your Firebase credentials:

cp .env.example .env.local

Edit .env.local with your Firebase project credentials:

2. Start your backend server

Make sure your backend is running at http://localhost:8080 with the /auth/login and /auth/logout endpoints.

Note: The Vite dev server is configured to proxy all /auth requests to http://localhost:8080, so you won't encounter CORS issues during development.

3. Start the dev server

npm run dev

This opens the demo app at http://localhost:5173 where you can:

• Test all authentication pages (Login, Signup, Password Reset)
• Try protected routes
• View the UI components in action

Testing in Another Project

To test the library in another project before publishing:

1. Build and pack the library

npm run build
npm pack
# Creates ktp-login-react-0.0.0.tgz

2. Install in your project

npm install /path/to/ktp-login-react/ktp-login-react-0.0.0.tgz

3. Install peer dependencies

npm install react react-dom firebase react-router-dom

After making changes to the library, rebuild and repack, then reinstall in your project. Note you should change the version number when doing this to avoid headaches.

Scripts

| Command | Description | | ----------------- | ------------------------------------------------------------------ | | npm run dev | Starts Vite in library mode for local development | | npm run lint | Runs ESLint over all ts/tsx sources | | npm run test | Executes the Vitest test suite | | npm run build | Produces dist/index.js and type declarations | | npm run preview | Serves the most recent build with Vite's preview server |

Releasing

Create a github release with the version number as the tag. The release will be built and deployed to the npm registry.