Firebase Auth Lite

Common errors

• Authentication error: auth/invalid-email

  cause The library now returns raw Firebase error codes instead of human-readable messages after v0.8.1.
  fix Implement a mapping logic in your application to translate Firebase error codes (e.g., 'auth/invalid-email') into user-friendly messages. Refer to the Firebase Auth error code documentation or the library's wiki for a comprehensive list.

• TypeError: Auth is not a constructor

  cause Attempting to use `Auth` as a function or incorrectly importing it as a named export.
  fix Ensure you are importing `Auth` as the default export using `import Auth from 'firebase-auth-lite';` and instantiating it with `new Auth(...)`.

• ReferenceError: fetch is not defined

  cause Running the library in an environment (e.g., older Node.js versions, certain test environments) that does not provide the Fetch API or localStorage.
  fix This library is browser-focused. Ensure it runs in a modern browser environment or use appropriate polyfills for `fetch` and `localStorage` if targeting older environments.

• Federated sign-in redirect loops or 'auth/redirect-url-mismatch'

  cause Incorrectly configured redirect URL for Federated Identity Providers (e.g., Google, Facebook OAuth), using the default Firebase handler URL instead of your application's URL.
  fix In the respective OAuth provider's developer console, update the Authorized Redirect URIs to specify the exact URL of the page within *your application* that handles the sign-in redirect, not the `https://[app-id].firebaseapp.com/__/auth/handler` URL.

Warnings

• breaking Error messages are no longer 'human friendly' English strings; instead, they are Firebase error code strings (e.g., 'auth/invalid-email'). You must implement your own mapping to user-friendly messages.
  Fix: Refer to the Firebase Auth error code documentation or the `firebase-auth-lite` wiki (github.com/samuelgozi/firebase-auth-lite/wiki/Error-codes-map) to map error codes to displayable messages for your users.
• breaking The `signInWithProvider` function no longer requires you to provide a list of supported providers during `Auth` instantiation. The function will now throw a server-returned error if a provider is unsupported.
  Fix: Remove any `supportedProviders` options from your `Auth` instantiation. The library will now automatically handle provider support via server responses.
• gotcha This library is in 'Beta' and 'work in progress'. The API is explicitly stated to change without warning until version 1.0 is released.
  Fix: Be prepared for frequent API changes and review release notes for each update. Pinning to a specific patch version is recommended in production environments.
• gotcha The library only supports modern browsers and is written with modern JavaScript (Fetch API, localStorage). You are responsible for transpiling the code for wider browser compatibility (e.g., via Babel).
  Fix: Integrate Babel or another transpiler into your build process to target older browsers or environments that do not fully support modern JS features used by this library.
• gotcha Sessions can currently only be persisted in `localStorage`. More options may be added in future versions.
  Fix: Be aware of this limitation if your application requires alternative session persistence mechanisms (e.g., cookies, sessionStorage). Plan accordingly for your security and UX requirements.
• gotcha When setting up Federated Identity Providers (e.g., Google, Facebook OAuth), you must whitelist *your application's own URL* as the redirect URI, not the Firebase-provided `firebaseapp.com` endpoint.
  Fix: In your OAuth provider's console (e.g., Google Cloud Console), configure the redirect URI to point to the specific page in your application that will handle the login redirect.

Install

• npm install firebase-auth-lite npm
• yarn add firebase-auth-lite yarn
• pnpm add firebase-auth-lite pnpm

Imports

• Auth
  wrong:

  import { Auth } from 'firebase-auth-lite';
  const Auth = require('firebase-auth-lite');

  correct:

  import Auth from 'firebase-auth-lite';

  Auth is the default export of the library. It is designed for ESM environments, typically used in modern browsers or via bundlers. Avoid named imports or CommonJS `require`.
• Auth instance
  wrong:

  const auth = Auth({ apiKey: 'YOUR_API_KEY' });

  correct:

  const auth = new Auth({ apiKey: 'YOUR_API_KEY' });

  Auth is a class and must be instantiated with the `new` keyword. The `apiKey` option is required for most authentication flows.

Quickstart

Demonstrates core authentication flows including user registration (sign-up), logging in (sign-in), retrieving the current user's session, and logging out (sign-out), showcasing typical API usage.

import Auth from 'firebase-auth-lite';

// Ensure you set your Firebase API Key, e.g., via environment variable
const API_KEY = process.env.FIREBASE_API_KEY ?? 'YOUR_FIREBASE_API_KEY_HERE';

// Instantiate the Auth client
const auth = new Auth({
  apiKey: API_KEY,
  // Optional: Add a custom app name if needed
  // appName: 'my-web-app'
});

async function runAuthDemo() {
  try {
    console.log('Attempting to sign up a new user...');
    // Example: Sign up with email and password
    const newUser = await auth.signUpWithEmailAndPassword('test@example.com', 'password123');
    console.log('New user signed up:', newUser.uid, newUser.email);

    console.log('\nAttempting to sign in existing user...');
    // Example: Sign in with email and password
    const user = await auth.signInWithEmailAndPassword('test@example.com', 'password123');
    console.log('User signed in:', user.uid, user.email);

    console.log('\nGetting current user session...');
    // Example: Get the currently signed-in user
    const currentUser = await auth.getCurrentUser();
    if (currentUser) {
      console.log('Current active user:', currentUser.uid);
    } else {
      console.log('No user currently signed in.');
    }

    console.log('\nAttempting to sign out user...');
    // Example: Sign out
    await auth.signOut();
    console.log('User successfully signed out.');

  } catch (error) {
    console.error('Authentication failed:', error.code || error.message);
    // As of v0.8.1, error messages are Firebase error codes.
    // Map these codes to user-friendly messages using the official Firebase docs or the library's wiki.
  }
}

runAuthDemo();